VAX DOCUMENT 
User Manual, Volume 2 

Order Number: AA-JT86A-TE 


TKis manual describes each of the VAX DOCUMENT doctypes and the 
tags that are specific to each of these doctypes. These tags are described 
by the doctype in which they can be used. 


Revision/Update Information: This is a new manual. 

Operating System and Version: VMS Version 4.4 or higher. 

MicroVMS Version 4.4 or higher. 

Software Version: VAX DOCUMENT Version 1.0. 


digital equipment corporation maynard, massachusetts 



July 1987 


The information in this document is subject to change without notice and should 
not be construed as a commitment by Digital Equipment Corporation. Digital 
Equipment Corporation assumes no responsibility for any errors that may appear 
in this document. 

The software described in this document is furnished under a license and may be 
used or copied only in accordance with the terms of such license. 

No responsibility is assurned for the use or reliability of software on equipment 
that is not supplied by Digital Equipment Corporation or its affiliated companies. 


Copyright ©1987 by Digital Equipment Corporation 

All Rights Reserved. 

Printed in U.S.A. 


The postpaid READER'S COMMENTS form on the last page of this document 
requests the user's critical evaluation to assist in preparing future documentation. 

The following are trademarks of Digital Equipment Corporation: 


DEC 

DEC/CMS 

DEC/MMS 

DECnet 

DECsystem-10 

DECSYSTEM-20 

DECUS 

DECwriter 


DIBOL 

EduSystem 

IAS 

MASSBUS 

PDP 

PDT 

RSTS 

RSX 


UNIBUS 

VAX 

VAXcluster 

VMS 

yM-- 



ZK4459 


This document was prepared using VAX DOCUMENT, Version 1.0 



VAX DOCUMENT 
User Manual, Volume 2 

Order Number; AA-JT86A-TE 


TKis manual describes each of the VAX DOCUMENT doctypes and the 
tags that are specific to each of these doctypes. These tags are described 
by the doctype in which they can be used. 


Revision/Update Information: This is a new manual. 

Operating System and Version: VMS Version 4.4 or higher. 

MicroVMS Version 4.4 or higher. 

Software Version: VAX DOCUMENT Version 1.0. 


digital equipment corporation maynard, massachusetts 



July 1987 


The information in this document is subject to change without notice and should 
not be construed as a commitment by Digital Equipment Corporation. Digital 
Equipment Corporation assumes no responsibility for any errors that may appear 
in this document. 

The software described in this document is furnished under a license and may be 
used or copied only in accordance with the terms of such license. 

No responsibility is assumed for the use or reliability of software on equipment 
that is not supplied by Digital Equipment Corporation or its affiliated companies. 


Copyright ©1987 by Digital Equipment Corporation 

All Rights Reserved. 

Printed in U.S.A. 


The postpaid READER'S COMMENTS form on the last page of this document 
requests the user's critical evaluation to assist in preparing future documentation. 

The following are trademarks of Digital Equipment Corporation: 


DEC 

DEC/CMS 

DEC/MMS 

DECnet 

DECsystem-10 

DECSYSTEM-20 

DECUS 

DECwriter 


DIBOL 

EduSystem 

IAS 

MASSBUS 

PDP 

PDT 

RSTS 

RSX 


UNIBUS 

VAX 

VAXcluster 

VMS 

VT 




TM 


ZK4459 

This document was prepared using VAX DOCUMENT, Version 1.0 



Contents 


PREFACE 

xiii 


CHAPTER 1 

OVERVIEW OF THE DOCTYPE-SPECIFIC TAGS 

1-1 

CHAPTER 2 

USING THE ARTICLE DOCTYPE 

2-1 

2.1 

ARTICLE DOCTYPE-SPECIFIC TAGS 

2.1.1 Titles and Subtitles 

2-2 

2-3 


2.1.2 

Author Information 

2-3 


2.1.3 

Abstracts, Source Notes, and Acknowledgments 

2-4 


2.1.4 

Headings 

2-5 


2.1.5 

Running Titles 

2-5 


2.1.6 

Oiiotations 

2-5 


2.1.7 

Back Notes and Reference Notes 

2-6 


2.1.7.1 Back Notes • 2-6 

2.1.7.2 Reference Notes • 2-7 


2.1.8 Bibliographies __ 2-7 


2.2 

IMPROVING THE FORMAT OF A TWO-COLUMN DOCTYPE 

2.2.1 Line Breaks in Columns 

2-8 

2-8 


2.2.2 

Wide Tables and Examples 

2-9 


2.2.3 

Final Adjustment of Holiimn and Page Breaks 

2-9 




2.3 

A SAMPLE USE OF THE ARTICLE DOCTYPE TAGS 

2-11 


CHAPTERS USING THE LETTER DOCTYPE 3-1 


3.1 SAMPLE USES OF THE LETTER DOCTYPE TAGS 3-2 

3.1.1 A Sample Memo _ 3—3 

3.1.2 A Sample Letter _ 3-5 


III 






Contents 


CHAPTER 4 

USING THE MANUAL DOCTYPE 

4-1 

4.1 

A SAMPLE OF THE MANUAL DOCTYPE 

4-1 

CHAPTER 5 

USING THE MILSPEC DOCTYPE 

5-1 

5.1 

WRITING A DOCUMENT ACCORDING TO MIL-STD-490A 

5-2 

5.2 

WRITING DATA ITEM DESCRIPTION DOCUMENTS 

5-3 

5.3 

A SAMPLE USE OF THE MILSPEC DOCTYPE TAGS 

5-6 

CHAPTER 6 

USING THE OVERHEADS DOCTYPE 

6-3 

6.1 

SAMPLE USE OF THE OVERHEADS DOCTYPE TAGS 

6-3 

CHAPTER 7 

USING THE REPORT DOCTYPE 

7-1 

7.1 

A SAMPLE USE OF THE REPORT DOCTYPE TAGS 

7-2 

CHAPTER 8 

USING THE SOFTWARE DOCTYPE 

8-1 

8.1 

SOFTWARE DOCTYPE-SPECIFIC TAGS 

8.1.1 Documenting Terminal Keys and Keypads 

8.1.1.1 Describing Individual Keys • 8-2 

8.1.1.2 Describing Keypads and Keypad Keys • 8-5 

8.1.2 Documenting Code Fragments 

8.1.3 Documenting Software Messages 

8.1.4 Documenting Arguments, Parameters and Qualifiers _ 

8.1.5 Creating A Series of Interactive or Code Examples 

8-2 

8-2 

8-8 

8-10 

8-14 

8-18 

8.2 

USING THE REFERENCE TEMPLATES 

8.2.1 Documenting Reference-Elements within Templates _ 

8-19 

8-23. 


IV 


Contents 


8.3 CREATING YOUR OWN REFERENCE TEMPLATE TAGS 8-25 

8.3.1 Creating Your Own Template Lists _ 8-25 

8.3.2 Creating Your Own Template Sections _ 8—27 

8.3.3 Creating Your Own Template Tables _ 8-29 


8.4 MODIFYING THE REFERENCE TEMPLATES 8-31 

8.4.1 Modifying Default Headings Within a Template _ 8-31 

8.4.2 Using the Template-enabling Tags _ 8-33 

8.4.3 Using the <SET_TEMPLATE_tempiatename> Tags _ 8—34 


8.5 USING THE COMMAND TEMPLATE 8-35 

8.5.1 Sample SDML File of the Command template _ 8-37 

8.5.2 Sample Output File of the Command Template _ 8-39 


8.6 USING THE ROUTINE TEMPLATE 8-42 

8.6.1 Sample SDML File of the Routine Template __ 8-43 

8.6.2 Sample Output File of the Routine Template _ 8-44 


8.7 USING THE STATEMENT TEMPLATE 8-48 

8.7.1 Sample SDML File of the Statement Template _ 8-49 

8.7.2 Sample Output File of the Statement Template _ 8-50 


8.8 USING THE TAG TEMPLATE 8-53 

8.8.1 Sample SDML File of the Tag Template _ 8-54 

8.8.2 Sample Output File of the Tag Template __ 8-55 


V 









Contents 


CHAPTER 9 


CHAPTER 10 


ARTICLE DOCTYPE TAG REFERENCE 9-1 


<ABSTRACT> 

9-2 

<ACKNOWLEDGMENTS> 

9-3 

<AUTHOR> 

9-4 

<AUTHOR_ADDR> 

9-6 

<AUTHOR_AFF> 

9-8 

<AUTHOR_LIST> 

9-9 

<BACK_NOTE> 

9-10 

<BACK_NOTES> 

9-12 

<BIBLIOGRAPHY> 

9-13 

<BIB_ENTRY> 

9-14 

<COLUMN> 

9-15 

<DOCUMENT_ATTRIBUTES> 

9-17 

<QUOTATION> 

9-20 

<REF_NOTE> 

9-21 

<REF_NOTES> 

9-23 

<RUNNING_FEET> 

9-24 

<RUNNING_TITLE> 

9-25 

<SOURCE_NOTE> 

9-27 

<SUBTITLE> 

9-28 

<TITLE> 

9-29 

<TITLE_SECTION> 

9-30 

<VITA> 

9-31 


LETTER DOCTYPE TAG REFERENCE 


<CC> 

10-2 

<CCLIST> 

10-4 

<CHEAD> 

10-5 

<CLOSING> 

10-7 

<DISTLIST> 

10-8 

<FROM_ADDRESS> 

10-9 

<HEAD> 

10-11 

<MEMO_DATE> 

10-13 

<MEMO_FROM> 

10-15 

<MEMO_HEADER> 

10-17 

<MEMO_LINE> 

10-18 

<MEMO_TO> 

10-20 

<SALUTATION> 

10-22 

<SUBJECT> 

10-23 

<TO_ADDRESS> 

10-24 


10-1 


VI 





Contents 


CHAPTER 11 MILSPEC DOCTYPE TAG REFERENCE 11-1 

<SET_APPENDIX_NUMBER> 11-2 

<SIGNATURE_LINE> 11-4 

<SIGNATURE_LIST> 11-6 

<SPECIFICATION_INFO> 11-8 

<SPEC_TITLE> 11-10 

<SUBTITLE> 11-11 


CHAPTER 12 OVERHEADS DOCTYPE TAG REFERENCE 12-1 

< AUTHOR_INFO> 12-2 

< AUTO_NUMBER> 12-3 

< I NTRO_SU BTITLE > 12-4 

<INTRO_TITLE> 12-5 

<RUNNING_FEET> 12-6 

<RUNNIIMG_TITLE> 12-8 

<SLIDE> 12-10 

<SUBTITLE> 12-12 

<TEXT_SIZE> 12-13 

<TITLE> 12-15 

<TOPIC> 12-16 


CHAPTER 13 REPORT DOCTYPE TAG REFERENCE 13-1 

<AUTHOR> 13-2 

<BYLINE> 13-4 

<CHEAD> 13-6 

<COLUMN> 13-8 

<DOCUMENT_ATTRIBUTES> 13-10 

<HEAD> 13-13 

<LEVEL> 13-15 

<OUTLINE> 13-16 

<RUNNING_FEET> 13-18 

<RUNNING_TITLE> 13-19 

<SECTION> 13-21 

<SHOW_LEVELS> 13-23 

<SIGNATURES> 13-25 


vii 





Contents 


CHAPTER 14 


14.1 


SOFTWARE DOCTYPE TAG REFERENCE 


THE SOFTWARE DOCTYPE TAGS 


<ARGDEFLIST> 

14-2 

<ARGDEF> 

14-5 

<ARGITEM> 

14-6 

<ARGUMENT> 

14-8 

<AUTHOR> 

14-9 

<BYLINE> 

14-11 

<CPOS> 

14-13 

<DELETE_KEY> 

14-14 

<DISPLAY> 

14-15 

<DOCUMENT_ATTRIBUTES> 

14-17 

<EXAMPLE_SEQUENCE> 

14-20 

<EXAMPLES_INTRO> 

14-22 

<EXC> 

14-24 

<EXI> 

14-25 

<EXTEXT> 

14-27 

<GRAPHIC> 

14-28 

<KEY> 

14-29 

<KEY_NAME> 

14-31 

<KEYPAD> 

14-32 

<KEYPAD_ENDROW> 

14-35 

<KEYPAD_ROW> 

14-36 

< KEYPAD-SECTION > 

14-38 

<KEY_PLUS> 

14-41 

<KEY_SEQUENCE> 

14-42 

<KEY_TYPE> 

14-44 

<MESSAGE_SECTION> 

14-45 

<MESSAGE_TYPE> 

14-48 

<MSG> 

14-49 

<MSGS> 

14-51 

<MSG_TEXT> 

14-53 

<PARAMDEF> 

14-54 

<PARAMDEFLIST> 

14-55 

<PARAMITEM> 

14-58 

<QPAIR> 

14-60 

<QUAL_LIST> 

14-61 

<QUAL_LIST_DEFAULT_HEADS> 

14-64 

<QUAL_LIST_HEADS> 

14-65 

<QUALDEF> 

14-66 


14-1 


14-1 


viii 



Contents 


<QUALDEFLIST> 14-67 

<QUALITEM> 14-70 

<RUNNING_FEET> 14-72 

<RUNNING_TITLE> 14-73 

<SIGNATURES> 14-75 

<SYNTAX> 14-76 

<SYNTAX_DEFAULT_HEAD> 14-78 


14.2 TAGS COMMON TO ALL REFERENCE TEMPLATES 14-80 

<DESCRIPTION> 14-81 

<OVERVIEW> 14-84 

<SET_TEMPLATE_HEADING> 14-85 

<SET_TEMPLATE_LIST> 14-87 

<SET_TEMPLATE_PARA> 14-89 

<SET_TEMPLATE_TABLE> 14-91 


14.3 THE COMMAND REFERENCE TEMPLATE TAGS 
<COMMAND> 
<COMMAND_SECTION> 

<FCMD> 

<FORMAT> 

<FPARM> 

<FPARMS> 

<PROMPT> 

<PROMPTS> 

<RESTRICTIONS> 

<RETURN_VALUE> 

<RITEM> 

<SET_TEMPLATE_COMMAND> 

<SET_TEMPLATE_SUBCOMMAND> 

<SUBCOMMAND> 

<SUBCOMMAND_SECTION> 

<SUBCOMMAND_SECTION_HEAD> 


14.4 THE ROUTINE REFERENCE TEMPLATE TAGS 


14-125 

<ARGTEXT> 

14-126 


<FARG> 

14-127 


<FARGS> 

14-129 


<FFUNC> 

14-131 


<FORMAT> 

14-133 




ix 


14-94 

14-95 

14-97 

14-101 

14-104 

14-106 

14-108 

14-110 

14-112 

14-113 

14-115 

14-116 

14-117 

14-119 

14-121 

14-123 

14-124 





Contents 



<FRTN> 

14-135 



<RETTEXT> 

14-137 



<RETURNS> 

14-138 



<ROUTINE> 

14-140 



<ROUTINE_SECTION> 

14-142 



<RSDEFLIST> 

14-146 



<RSITEM> 

14-148 



<SET_TEMPLATE_ROUTIIME> 

14-149 


14.5 

THE STATEMENT REFERENCE TEMPLATE TAGS 


14-151 


<CONSTRUCT> 

14-152 



<CONSTRUCT_LIST> 

14-154 



<FCMD> 

14-157 



<FFUNC> 

14-160 



<FORMAT_SUBHEAD> 

14-162 



<FPARM> 

14-164 



<FPARMS> 

14-166 



<FUNCTION> 

14-168 



<SET_TEMPLATE_STATEMENT> 

14-169 



<STATEMENT> 

14-171 



<STATEMENT_FORMAT> 

14-172 



<STATEMENT_LINE> 

14-174 



<STATEMENT_SECTION> 

14-177 


14.6 

THE TAG REFERENCE TEMPLATE TAGS 


14-181 


<FORMAT> 

14-182 



<FTAG> 

14-183 



<RELATED_ITEM> 

14-185 



<RELATED_TAG> 

14-186 



<RELATED_TAGS> 

14-187 



<RESTRICTIONS> 

14-189 



<RITEM> 

14-191 



<SDML_TAG> 

14-192 



<SET_TEMPLATE_TAG> 

14-193 



<TAG_SECTION> 

14-195 



<TERMINATING_TAG> 

14-199 



X 


Contents 


INDEX 


TABLES 

2- 1 Tags Available in the ARTICLE Doctype _ 2-1 

3- 1 Tags Available In the LETTER Doctype _ 3-1 

5-1 Tags Available in the MILSPEC Doctype _ 5-1 

5- 2 MILSPEC Doctype Data Item Description Templates _ 5-5 

6- 1 Tags Available in the OVERHEADS Doctype _ 6-2 

7- 1 Tags Available in the REPORT Doctype _ 7-1 

8- 1 Default Headings of Reference Template Tags _ 8-32 

8-2 Tags Available in the Command Template in their Standard 

Order _ 8-36 

8-3 Tags Available in the Routine Template in their Standard 

Order _ 8-42 

8-4 Tags Available in the Statement Template in their Standard 

Order _^_ 8-48 

8- 5 Tags Available in the Tag Template in their Standard Order _ 8-53 

9- 1 Doctype-specific Tags Enabled by the <document_attributes> 

Tag _ 9-18 

13- 1 Doctype-specific Tags Enabled by the <document_attributes> 

tag _- 13-11 

14- 1 Doctype-specific Tags Enabled by the <document_attributes> 

tag _ 14-18 


xi 






Preface 


Document Structure 

This manual describes the VAX DOCUMENT doctypes and the tags available 
within each doctype. 

• Chapter 1 provides an overview of all the doctypes discussed in this 
manual. 

• Chapters 2 through 8 provide tutorial information on each of the doctypes 
and their tags. 

• Chapters 9 through 14 provide the reference information on the tags 
available within each of these doctypes. 

The VAX DOCUMENT User Manual, Volume 1 provides a complete description 
of the global tags as well as tutorial information on how to use them to create 
a document. Global tags are tags that can be used in any doctype. 

The VAX DOCUMENT Design Samples manual provides information on each 
of the doctype designs available in VAX DOCUMENT and provides samples 
of each design. 


Intended Audience 

This book is intended for writers, editors, and general users who wish to 
produce articles, business letters, military specifications, technical manuals, 
or overhead slides using VAX DOCUMENT. Familiarity with a text editor is 
presumed, as is a basic knowledge of the VMS operating system. 


Conventions 

Capitalized words within syntax statements indicate specific commands or 
keywords to be entered. Lowercase words indicate user-specified parameters 
or arguments. Optional items within syntax statements are enclosed in 
brackets. 

Within reference chapters, the discussion of each tag follows a fixed order. 
First, the name of the tag is followed by a brief overview that describes the 
purpose of the tag. Following the overview is a format section that displays 
the syntax of the tag: any optional or required arguments and the information 
required, any related tags, any restrictions on the use of the tag, and any 
required terminators, if needed. 

The category of "related tag" has been defined broadly. A tag is related to the 
tag under discussion if one of the following criteria are met: 

• It is required for use of the tag under discussion. 

• It marks a text element of the same kind as the tag under discussion. 

• It is commonly used with the tag under discussion. 
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Preface 


Following the format section is an optional description section. The 
description expands the overview and presents more detailed information 
on the use of the tag. Not every tag requires a description section. 

The discussion of a tag concludes with at least one example, or a reference 
to an example. The example shows how the tag is used in a source file and 
what the formatted result is when the file is processed for printing. 

Output examples within this manual may vary depending on the doctype 
you processed the example under, or depending on whether any doctype 
modifications have been made to your local installation of VAX DOCUMENT. 
Each output example is introduced by a form of the sentence "This example 
may produce the following output" to remind you that the output examples 
may vary. 


Associated Documents 

The reader is presumed to be familiar with the following documents: 

• Step-by-Step: Writing with VAX DOCUMENT 

• VAX DOCUMENT User Manual, Volume 1 

Other books in the documentation set for VAX DOCUMENT Version 1.0 are 
as follows: 

• VAX DOCUMENT Design Samples 

• VAX DOCUMENT Doctype Designer's Guide 
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1 Overview of the Doctype-Specific Tags 


This manual describes the VAX DOCUMENT doctypes and their associated 
tags. These doctype-specific tags are restricted to certain doctypes and so 
are not available in all doctypes as are the global tags described in the 
VAX DOCUMENT User Manual, Volume 1. 

For example, the < SALUTATION > tag is a doctype-specific tag available only 
in the LETTER doctype. This tag is restricted to the LETTER doctype because 
it is only when you write a letter or memo that you want the output format 
associated with this tag. VAX DOCUMENT limits tags to specific doctypes to 
make the system more modular and to reduce the number of tags you must 
learn to use. 

Using this Manual 

The doctypes and doctype-specific tags are described in this manual in tutorial 
chapters (Chapters 2 through 8) and in reference chapters (Chapters 9 —14), 

Each doctype and its designs is explained in a tutorial chapter, which 
describes how to use that doctype and what doctype-specific tags and global 
tags are available within it (some doctypes do not use all of the global tags). 
These tutorial chapters are ordered alphabetically by doctype name. Each 
tutorial chapter includes a short sample of at least one SDML file that uses 
these tags. Each of these sample input files is followed by an output sample 
of that SDML file. See VAX DOCUMENT Design Samples for detailed samples 
of each doctype design. 

The reference chapters describe the syntax and restrictions associated with 
each doctype-specific tag. These chapters are also arranged alphabetically by 
doctype. The following table lists the supported doctypes, explains what each 
doctype is generally used for, and indicates which chapters in this manual 
describe them. 


Doctype 

Keyword 

Used to Create 

Tutorial 

Chapter 

Reference 

Chapter 

ARTICLE 

Articles 

Chapter 2 

Chapter 9 

LETTER 

Letters and memos 

Chapter 3 

Chapter 10 

MANUAL 

User manuals 

Chapter 4 

Because this doctype uses only the global 
tags, no reference chapter is needed. 

MILSPEC 

Military specifications 

Chapter 5 

Chapter 11 

OVERHEADS 

Overhead slides for 
transparencies 

Chapter 6 

Chapter 12 

REPORT 

General-purpose documents or 
formal outlines 

Chapter 7 

Chapter 13 

SOFTWARE 

User manuals containing 
software-specific information 

Chapter 8 

Chapter 14 
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2 Using the ARTICLE Doctype 


f 


The ARTICLE doctype lets you create two-column articles in an 8^ x 11 inch 
format with numbered or unnumbered headings. The ARTICLE doctype has 
a single design. You process files under this doctype by using the ARTICLE 
doctype keyword on the DOCUMENT command line. 

This doctype supports all of the VAX DOCUMENT global tags with the 
following exceptions: 

• <CHAPTER> 

• <FRONT_MATTER> 

• < RE VISION >, <MARK>,and < UPDATE-RANGE > 

• The MULTIPAGE keyword is not available as an argument to the 

<EXAMPLE-ATTRIBUTES> , <FIGURE-ATTRIBUTES > , and <TABLE- 
ATTRIBUTES> tags. This means that formal examples, figures, and tables 
are restricted to a length of one column or less. 

See the VAX DOCUMENT User Manual, Volume 1 for more information on 
global tags. See VAX DOCUMENT Design Samples for additional information 
on the design of the ARTICLE doctype. 

Table 2-1 summarizes the tags available in the ARTICLE doctype and 
provides a brief description of each tag. Chapter 9 contains the reference 
information on these tags. 

Table 2-1 Tags Available in the ARTICLE Doctype 


Tag Name 

<ABSTRACT> 

< acknowledgments> 

<AUTH0R> 

<author_addr> 

<AUTHOR_AFF> 

<author_list> 

<BACK-NOTE> 

<BACK_N0TES> 

<BIBLIOGRAPHY> 

< BIB-ENTRY > 

<COLUMN> 

<D0CUMENT-ATTRIBUTES> 


Description 

Creates an article abstract. 

Creates an acknowledgments section in an article. 

Specifies an author of an article. 

Specifies the address of the author. 

Specifies information about the organizational affiliation of the author. 
Creates a list of authors for an article with multiple authors. 

Creates a back note entry, and creates a superscript reference number in 
the article text. 

Causes any accumulated back notes to be output. 

Begins a bibliography. 

Specifies a single entry in a bibliography. 

Specifies that a new column of output should begin. 

Enables doctype-specific tags that override the default design format of 
the ARTICLE doctype. 
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Using the ARTICLE Doctype 


Table 2-1 (Cent.) Tags Available in the ARTICLE Doctype 


Tag Name 

<QUOTATION> 

<REF_NOTE> 

<REF_NOTES> 

<RUNNING_FEET> 

<RUNNING_TITLE> 

<SOURCE_NOTE> 

<SUBTITLE> 

<TITLE> 

< TITLE-SECTION > 
<VITA> 


Description 

Begins a quotation in which the spacing is retained and the text is not filled 
or justified. 

Specifies the text of a reference note, and creates a bracketed reference 
number in the article text. 

Causes all accumulated reference notes to be output. 

Creates a heading at the bottom of each page. 

Creates a one- or two-line heading at the top of each page. 

Provides information pertaining to the original source of information for an 
article. 

Specifies a subtitle for an article. 

Specifies the main title line for an article. 

Begins the title section of an article that spans both columns of the article. 
Provides information about the author's professional history. 


2.1 ARTICLE Doctype-specific Tags 

The ARTICLE doctype provides tags that let you perform the following 

functions: 

• Create an article title and subtitle in either a one- or two-column format. 

• Specify an author (or list of authors) for the article, and provide 
information about the author's professional history, address, affiliation or 
other information. 

• Create abstracts, source notes, and acknowledgments. 

• Specify whether primary headings should be numbered or unnumbered. 

• Create running titles and running feet. 

• Create quotations in which spacing and line breaks are retained as 
entered. 

• Create back notes or reference notes which are automatically numbered 
and collated. 

• Create bibliographies. 
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Using the ARTICLE Doctype. 


2.1.1 Titles and Subtitles 

You can create a title for an article using the < title _SECTiON> , < title > , 
and < SUBTITLE > tags. The < title > and < subtitle > tags are used to 
create titles and subtitles for an article. By default, these tags create a title or 
subtitle that is restricted to the first column of the article. 

The < TITLE _SECTiON> tag begins a title section that spans both columns 
of the article and enlarges the type faces output by the < title > and 
< SUBTITLE > tags. Typically you would want to use only the < TITLE > 
and <SUBTITLE> tags in the context of the <title_section> tag, but you 
may also want to use the <AUTHOR> tag as well to have the author's name 
span both columns. Note that the output of the <AUTHOR> tag will not be 
enlarged. 

In the following example, a title and subtitle are created that use the full page 
width of the article by using the < TITLE—SECTION > tag. 

<TITLE_SECTION> 

<TITLE>(A Guide to Instrument Care) 

<SUBTITLE>(A Professional’s View) 

<ENDTITLE_SECTION> 

You can have your title and subtitle appear only in the first column of the 
article by using them without the < title-SECTION > tag. 


2.1.2 Author Information 

VAX DOCUMENT provides several tags to specify authors and author 
information in the ARTICLE doctype. 

Use the <AUTHOR> and <AUTHOR-LiST> tags to specify one or more 
authors for an article. Use the following tags to specify information about an 
author: 

• <AUTHOR-ADDR> specifies the address of the author 

• <AUTHOR_AFF> specifies information about the professional or 
educational affiliations of the author 

• <VITA> specifies the professional history of the author 

These tags will appear in your output file in whatever order you place them 
in your SDML file, with the exception of the <VITA> tag, which places its 
text argument at the bottom of the current text column of output. 

In the following example, a title, subtitle and author's name and professional 
history are created using the <title> , <subtitle> , <author> , and 
<VITA> tags. 

The output from this example would place the title, subtitle, and author's 
name at the top of the first column, and would place the text specified as the 
argument to the <VITA> tag at the bottom of the first column. The text of 
this example is assumed to be in the first paragraph of the article. 

<TITLE>(Computer Graphics) 

<SUBTITLE>(Everyone Likes It) 

<AUTH0R>(G.R. Edwards) 

<VITA>(G.R. Edwards has used graphics editors extensively.) 

<P>Computer Graphics really are not for everyone, yet••• 
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You can also use the author information tags within the context of the 
< TITLE-SECTION > tag. In the following example, the title, subtitle, and 
author's name are output using the full page width because these tags are 
used in the context of the <title_SECTION> tag. The information on the 
author's affiliations, and then the text of the article, are output in a single 
column because those tags were used outside of the context of the < TITLE- 
SECTION> tag. 

<TITLE_SECTION> 

<TITLE>(Computer Graphics) 

<SUBTITLE>(Everyone Likes It) 

<AUTHOR>(G.R. Edwards) 

<ENDTITLE_SECTION> 

<AUTHOR_AFF>(G.R. Edwards is a senior consultant for Terminals, Inc.) 

<P>Computer Graphics really are not for everyone, yet... 


2.1.3 Abstracts, Source Notes, and Acknowledgments 

Abstract, source note, and acknowledgment sections are special formats that 
typically occur at the beginning or end of an article, depending on your 
preference. 

Abstracts 

Use the < ABSTRACT > tag to specify an abstract for an article. You can specify 
the < ABSTRACT > tag either within the context of the < TITLE-SECTION > tag 
or following it. 

In the following example, a short abstract is created within the context of the 
< TITLE-SECTION > tag. This causes the abstract to be formatted using the 
full page width rather than just a single column. The <AUTHOR> tag occurs 
outside of the context of the < TITLE-SECTION > tag and so is formatted using 
a single column. 

<TITLE_SECTION> 

<TITLE>(A Guide to Instrument Care) 

<ABSTRACT>(A summary of brass and keyboard instrument care fundamentals by 
a professional musician.) 

<ENDTITLE_SECTION.> 

<AUTHOR>(Dan Dover) 

Source Notes 

The <SOURCE-NOTE> tag lets you specify the origination of material for an 
article. In the following example, the output from the <sourcE-NOTE> tag 
is printed at the bottom of the current column of output. 

<S0URCE_N0TE>(From the Boston Globe 
<LINE>(<MCS>(COPYRIGHT) 1986 by the Boston Globe)) 

You can specify source information at the beginning or end of an article. 

Acknowledgments 

You can create a section for any acknowledgments you feel are necessary 
for your article using the <ACKNOWLEDGMENTS> tag. The text of the 
acknowledgment is entered as an argument to the < ACKNOWLEDGMENTS > 
tag. This tag outputs the heading "Acknowledgments" using the same format 
as the headings used by the <BACK-NOTES> and <REF-NOTES> tags. 
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The following example shows an acknowledgments section created using the 
<ACKNOWLEDGMENTS> tag. Note how it is used near the end of the SDML 
file with the <back_notes> and <REF_NOTES> tags. 

<REF_N0TES>(Bibliography) 

<BACK_NOTES>(References) 

<ACKNOWLEDGMENTS>(I am deeply indebted to my doctor 
for her support in this task.) 


2.1.4 Headings 

The ARTICLE doctype allows the global numbered heading tags ( <HEADl> , 
<HEAD2> , and so on) to provide a logical structure for your text. However, 
by default these headings are not numbered. You can specify that these 
headings be numbered by using the < DOCUMENT-ATTRIBUTES > tag as shown 
in the following example; 

<DOCUMENT_ATTRIBUTES> 

<SET_HEADINGS>(NUMBERED) 

<ENDDOCUMENT_ATTRIBUTES> 

In addition to the primary headings, you can use the global < SUBHEAD i> 
and <SUBHEAD2> tags to specify unnumbered paragraph topics or side 
headings as in the following example: 

<SUBHEAD1>(Rationale.)<P>The purpose of this experiment... 


2.1.5 Running Titles 

You can place a title at the top or bottom of all the pages of your article using 
the <RUNNING_TITLE> and <RUNNING_FEET> tags. 

The < RUNNING-FEET > tag accepts a single text argument, which it uses to 
create a title at the bottom of the page. The <RUNNING-TITLE> tag accepts 
one or two text arguments, which it uses to create a one- or two-line title at 
the top of the page. 

The following example shows a two-line running title being set for the top 
of the page using the <RUNNING-TITLE> tag and a single line running title 
being set for the bottom of the page using the <RUNNING-FEET> tag. 

<RUNNING_TITLE>(Mr. A. Author and\Mrs. B. Author) 

<RUNNING_FEET>(The Story of Our Life Together) 


2,1.6 Quotations 

You can use either the ARTICLE doctype < QUOTATION > tag or the global 
<SAMPLE-TEXT> tag to place extended quotations in an article. 

Use the < quotation > tag to format text that you want to appear exactly as 
it is entered into the SDML file. The following example shows a Haiku poem 
formatted using the <QUOTATlON> tag: 

<P>A similar Haiku follows. 

<qU0TATI0N> 

All lights are frozen; 

The cursor box blinks blandly. 

Soon, I see the dump. 

<ENDQU0TATI0N> 
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Use the global <SAMPLE_TEXT> tag to create an extended quotation that is 
to be filled and justified in the text. You must supply any quotation marks, 
paragraph spacing, and so on. The following example shows how you can 
use the <SAMPLE_TEXT> tag to create an extended quotation: 

As in the following text fragment: 

<SAMPLE_TEXT> 

<P><qU0TE> 

Many are the ways of mankind. As some strive for recognition, others seek 
obscurity. Surely, we are the strangest of creatures. 

<ENDQU0TE> 

<ENDSAMPLE_TEXT> 


2.1.7 Back Notes and Reference Notes 

You can use two types of automatically numbered notes in the ARTICLE 
doctype: back notes and reference notes. Back notes, sometimes referred 
to as end notes, are referenced in the text of an article using superscript 
numbers. Reference notes are similar to back notes, except that the references 
in the text are output using normal-sized numbers enclosed in brackets. 

References to each type of note are accumulated while the article is being 
processed, and are output at the end of the article. You should use only one 
of these two types of note in your article. 

You can also use the global <FOOTNOTE> tag to place footnotes at the 
bottom of a column of text. However, you should not use < FOOTNOTE > tag 
in an article in which you are using back notes. Both the <FOOT_NOTE> and 
the <BACK_NOTE> tags create superscript numbers for references, and that 
output would be extremely misleading and confusing. 


2.1.7.1 Back Notes 

Use the <BACK_NOTE> and the <BACK_NOTES> tags to create a set of back 
notes. The <BACK_NOTE> tag specifies the text of a note that is to be printed 
at the end of a document. You enter the <BACK_NOTE> tag in your SDML 
file wherever you want to provide a back note citation. VAX DOCUMENT 
sequentially numbers each of the back note entries and places the appropriate 
sequential number as a superscript in the output file. 

For example, if you want to cite the book Training Seagulls as a back note, 
and this back note was the third in your document, the text where you cited 
the book would appear as follows: 

These techniques are outlined in Training Seagulls 

Place the <back_notes> tag in your SDML file at the point you want the 
accumulated back notes to be printed. When the <back_notes> tag is 
processed, all the accumulated notes are output, with their correct numbers 
and with the text you specified as arguments to the <BACK_NOTE> tags. The 
^ back notes are not automatically output at the end of the article so that you 
can control their position in the article. 

The following example shows how to use the <BACK_NOTE> tag. The 
< BACK-NOTE > tag would be replaced by a superscript number in the output, 
and the note produced by that tag would be output near the end of the article 
using the <back_notes> tag. 
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As Ms. Roma so clearly stated <BACK_NOTE>(P.A. Roma, 

<QU0TE>(Computer-Chart Making 

from the Graphic Editor’s Perspective,) 

<EMPHASIS>(ACM Computer Graphics, SIGGRAPH ’99 Conf. Proc.), 
Vol 45. No. 3, July 1999, pp. 247-253.). 


<BACK_NOTES> 


2.1.7.2 Reference Notes 

You can create bibliographic reference notes by using the <REF_NOTE> , 
<REF_NOTES> and optionally the global <REFERENCE> tags. Place the 
<REF_NOTE> tag in your SDML file at the point at which you want the 
reference to appear. This tag is replaced in the output by a number in 
brackets, which corresponds to the number assigned to the note text, for 
example, [4]. 

Use the <ref_notes> tag to cause the text of the reference notes you have 
created using the <REF_NOTE> tag to be output along with its assigned 
numbers. Typically this tag is placed at the end of the SDML file, but you 
can have the references appear earlier. 

If you want to reference a source that you have already referenced using 
the <REF_NOTE> tag, you need to specify the symbol-name argument to 
that <REF_NOTE> tag and use the global <REFERENCE> tag to refer to that 
symbol. 

The following example shows a reference note created using the <REF_ 
NOTE> tag, a referral to that note using the global <REFERENCE> tag, 
and the printing of all the accumulated reference notes using the <REF_ 
NOTES> tag. Note how the <ref_note> tag was coded with the symbol 
CHICAGO—MAN, so that the subsequent < reference > tag could reference 
that symbol and use that same reference note number. 

Sorting entries word by word is preferred 
<REF_NOTE>(<EMPHASIS>(A Manual of Style,) 

The University of Chicago Press, 1969.\CHICAGO_MAN). 


<P>0veruse of emphasis can cause confusion <REFERENCE>(CHICAGO_MAN). 


<REF_NOTES>(References) 

If you want to create a bibliography that is not tied to references in the text of 
an article, you should use the <bibliography> tag. 


2.1.8 Bibliographies 

Use the < BIBLIOGRAPHY > tag to create a bibliography of related reading 
when you do not use numbered reference notes to reference other works in 
the text of the article. The < bibliography > tag enables the <bib_entry> 
tag and allows you to specify a heading for the bibliography as an argument 
to the < BIBLIOGRAPHY > tag. 

Each of the entries in the bibliography are created by specifying the entry as 
an argument to the <bib_entry> tag. When you use this tag, you should 
use the <EMPHASIS> and <QUOTE> tags to specify the entry. 
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In the following example a bibliography is shown with two entries: 

<BIBLIOGRAPHY>(Bibliography) 

<p>The following may also be of interest; 

<BIB_ENTRY>(<EMPHASIS>(Molecular Connectivity in Chemistry 
and Drug Research.) 

Lament B. Kier and Lowell H. Hall. Academic Press, 1983.) 

<BIB_ENTRY>(Arhnheim, Rudolph. <EMPHASIS>(Visual Thinking). 

University of California Press, Berkeley, 1984.) 

<ENDBIBLIOGRAPHY> 

Use the <REF_NOTE> and <ree_notes> tags to create numbered reference 
notes. 


2.2 Improving the Format of a Two-Column Doctype 

The ARTICLE and REPORT.TWOCOL doctypes let you create a two-column 
document. While these doctypes allow you to visualize what your document 
will look like when published, they are somewhat less flexible in terms of 
how they format SDML tags than the single-column doctypes. This section 
summarizes how you can improve the format of your two-column document. 


2.2.1 Line Breaks in Columns 

The width of the text column for paragraphs is much smaller in the two- 
column doctype than in the single-column doctypes. Furthermore, the left 
column is formatted right-justified. As you enter the text for your document 
into the SDML file, you need not be overly concerned about text paragraphs 
that exceed the right margin during text formatting. The text formatter issues 
the following message when a text line exceeds the right margin: 

"/,TEX-W-LINET00L0NG_P, line too long ... in paragraph . . . 

As you near completion of the edits on your document, you may want to use 
the global < hyphenate > and <keep> tags to improve the line breaks in 
your printed document. 

Use the global < HYPHENATE > tag to specify possible points of hyphenation 
in words the text formatter does not know how to hyphenate, but that you 
want to allow to hyphenate. This increases the number of places the text 
formatter can hyphenate the text, and so creates more even line breaks. 

Use the global <keep> tag to specify text that you do not want hyphenated 
(broken across a line) by the text formatter. Use this tag as sparingly as 
possible because it decreases the number of places the text formatter can 
hyphenate the text, and so makes it difficult for the text formatter to create 
well-placed line breaks. 

The text formatter constructs more well-formatted text lines in each column 
when it has more places at which it can hyphenate words in the text. The 
more places you allow the text formatter to hyphenate your text, the better 
your final output will be formatted. 
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2.2.2 Wide Tables and Examples 

When developing examples and tables using a two-column doctype, you 
should be careful of the following conditions: 

• Monospaced or unformatted output created using the < CODE-EXAMPLE > 
or < QUOTATION > tags that exceed the column width 

• The width of tables and figures (if your figures include monospaced 
examples or art) 

If you have a table, figure, or a monospaced example that is wider than 
the text column width, you can use the WIDE argument when you specify 
attributes for the tag. 

When the <table_attributes> or < figure-Attributes > tag is specified 
with the WIDE keyword to create a wide table or figure, that table or figure 
causes the two-column output to be suspended and the text entered before 
that table or figure will be placed in the two columns above the table or 
figure. 

The table or figure then will be output using the full page width, as if they 
occurred in a single-column doctype. Two-column formatting is restored after 
the table or figure ends, and the text after the table or figure begins again in 
the first column under the table or figure. 


2.2.3 Final Adjustment of Column and Page Breaks 

When you are working with a two-column doctype (such as ARTICLE or 
REPORT.TWOCOL), you may need to make some final adjustments to your 
paged output when your text is complete. This is because it is difficult to 
create good-looking pages within the constraints of a two-column document. 
Occasionally, a two-column document will need to have explicit line, column, 
and page breaks inserted into it to improve its appearance. 

You can use the < final-CLEANUP > tag in all doctypes to specify where text 
lines and pages should break by using the LINE—BREAK and PAGE—BREAK 
keywords as arguments. In two-column doctypes, you can begin a new 
column of text by using the COLUMN—BREAK keyword to the <finaL- 
CLEANUP> tag, or the < COLUMN > tag, which is available in the ARTICLE 
and REPORT.TWOCOL doctypes. 

Column Breaks 

When the text formatter creates a two-column page, it breaks the text into two 
columns so as to create a page in which the columns are of as nearly equal 
length as possible (this is sometimes called "bottoming out"). Certain text 
elements (such as tables and figures) cannot be easily broken across columns. 
The text formatter uses vertical space to adjust the length of the columns, 
therefore, you may see large amounts of vertical white space preceding and 
following those text elements that accept a variable amount of white space 
(for example, headings, lists and tables). 

You can specify that columns be explicitly broken by using the <COLUMN> 
or < FINAL-CLEANUP > (COLUMN-BREAK) tags. You should use the 
< COLUMN > tag only when you want the subsequent text to always begin a 
new column, regardless of any changes you make to the text. You should use 
the < FINAL-CLEANUP > (COLUMN-BREAK) tag only after your text is finished 
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and you want to improve the appearance of your document by specifying a 
new column of text. 

In either case, if the current text is in the first column of a page, the request to 
start a new column places the next text in the second column. If the current 
text is in the second column of a page, the request results in a new page of 
output. 

In some circumstances, the output of a two-column page may appear to 
have lost vertical space before a text element; for example, a hea^ng tag 
may have no space before it. When this occurs in processing a two-column 
doctype, you should ignore the occurrence until you are ready to give your 
document a final go-over. If the space is still being lost, use the < FINAL- 
CLEANUP > (SPECIAL-BREAK) tag. For example, suppose the following lines 
represent fragments of a two-column page: 


Major Heading 


Next Heading 


end of text in this - 

In the previous example, the spacing appears to be lost above the 
heading "Next Heading." You can correct this by placing the <final_ 
CLEANUP > (SPECIAL-BREAK) tag in the SDML file between the words that are 
output on the final line of the first column as in the following example: 

<P>An example shows what happens to the end of 
<FINAL_CLEANUP>(SPECIAL.BREAK) 
text in this column. 

You should need to use this special column break only in rare instances. 

Page Breaks 

A new page of output is explicitly started whenever the following conditions 
exist: 

• A < COLUMN > or < FINAL-CLEANUP > (COLUMN-BREAK) occurs in the right 
text column and so results in a new page of output 

• A < FINAL-CLEANUP > (PAGE-BREAK) tag is used to request that text start 
on a new page 

In either of these situations, the current page is set in two columns, without 
balancing the columns. The length of the text in either column may be less 
than that of the regular balanced page. 
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2.3 A Sample Use of the ARTICLE Doctype Tags 

This section contains an example of an article created using the ARTICLE 
doctype tags. You may find this sample useful in understanding how the tags 
can be used to create two-column articles. 

The SDML code for the article is shown first, followed by the output from 
that SDML code. 

<TITLE_SECTION> 

<TITLE>(MUSIC. MAESTRO) 

<SUBTITLE>(A Guide to Instrument Care) 

<ENDTITLE_SECTION> 

<AUTHOR_LIST>(By) 

<AUTHOR>(Dan Dover) 

<AUTH0R>(Dunstan Frobisher) 

<ENDAUTHOR_LIST> 

<P>Musical instruments of any kind can bring years of enjoyment to both the 
player, and hopefully the listener, as long as the musical instrument is cared 
for properly. Where diligence and discipline can make one a proficient 
player, care and cleaning can also make one an efficient player. 

<P>This article discusses the basic care of several musical instruments which 
can be carried over to other musical instruments that will not be discussed 
here. 

<CHEAD>(Keyboard Instruments) 

<P>The first rule in caring for any keyboard instrument is <EMPHASIS>(Are your 
hands clean?) <REF_NOTE>(<EMPHASIS>(Tickling the Ivories; Piano for Beginners), 
Architect Press. 1982.). Peanut butter and jelly tends to make the keys stick. 

Also, grime and dirt will scratch the keys and get between them as well. 

<P>Even the natural oils of your hand have a detrimental effect on the 
keyboard. It is always a good idea to wash your hands before playing the piano, 
organ, or other keyboard instrument. And after you are through playing, take a 
warm, damp cloth and wipe down the keyboard. This removes any residual hand 
oil from the keys. 

<P>The second rule for keyboard care is <EMPHASIS>(tuning). Like Mary Edith 
Whiteout of the Hanscom Music Company says; 

<QUOTATIQN> 

You can tell the quality of a pianist 
by the pitch of their instrument. 

A well-tuned piano is as much a joy, 
as a badly-tuned piano is a horror. 

<ENDqU0TATI0N> 

<P>Have your piano tuned every six months (for the average piano player); if 
you play more than four hours a day, a tune up every three to four months is 
recommended. 

<P>If your organ, or your accordion goes out of tune, take it to a repairman 
and get the offending note fixed. In summary, basic care for your keyboard 
instrument entails; 

<LIST>(NUMBERED) 

<LE>Clean hands and a clean instrument; wash your hands before, wash the 
keyboard after 

<LE>Tune your instrument regularly; 6 months - average use, 3 to 4 months 
for heavy use 
<ENDLIST> 

<CHEAD>(Brass Instruments) 
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<P>The first rule in caring for any brass instrument is <EMPHASIS>(Is your 
mouth clean?) Be sure to brush your teeth and rinse your mouth if you are 
going to play the trumpet <REF_NOTE>(<EMPHASIS>(Trumpeter Lullaby: Caring for 
Your Horn), County Ecks Press, 1985), trombone <REF_NOTE>(<EMPHASIS>(Trombone 
Exercises) Emerald Books, 1983), or other brass instrument. Food particles 
left in your mouth will foul up the valves and slides. It may even cause a 
restriction of the air flow, the instrument to go out of tune, or even damage 
it permanently. 

<P>The second rule is <EMPHASIS>(Oil your valves and slides regularly.) Use 
the recommended oil for your instrument. This will ensure that part movement 
happens smoothly and quickly. 

<P>The third rule is to <EMPHASIS>(Polish your instrument after each use) with 
a warm, damp cloth. This will help keep it from tarnishing from the natural 
oils in your hand. In addition to this, you should use a recommended brass 
polish every month. In summary, basic care for your brass instrument entails: 

<LIST>(NUMBERED) 

<LE>A clean mouth 
<LE>0iled valves and slides 
<LE>Polishing on a regular bdsis 
<ENDLIST> 

<REF_N0TES>(Additional Reading) 

This example may produce the following output if processed using the 
ARTICLE keyword. 
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Sample Output of Article Doctype 


MUSia MAESTRO 

A Guide to Instrument Care 


By 

Dan Dover 
Dunstan Frobisher 

Musical instruments of any kind can bring years 
of enjoyment to both the player, and hopefully the 
listener, as long as the musical instrument is cared for 
properly. Where diligence and discipline can make 
one a proficient player, care and cleaning can also 
make one an efficient player. 

This article discusses the basic care of several mu¬ 
sical instruments which can be carried over to other 
musical instruments that will not be discussed here. 

Keyboard Instruments 

The first rule in caring for any keyboard instrument 
is Are your hands clean? [1] . Peanut butter and jelly 
tends to make the keys stick. Also, grime and dirt 
will scratch the keys and get between them as well. 

Even the natural oils of your hand have a detri¬ 
mental effect on the keyboard. It is always a good 
idea to wash your hands before playing the piano, 
organ, or other keyboard instrument. And after you 
are through playing, take a warm, damp cloth and 
wipe down the keyboard. This removes any residual 
hand oil from the keys. 

The second rule for keyboard care is tuning. Like 
Mary Edith Whiteout of the Hanscom Music Com¬ 
pany says: 

You can tell the quality of a pianist 
by the pitch of their instrument. 

A well-tuned piano is as much a joy, 
as a badly-tuned piano is a horror. 

Have your piano tuned every six months (for the 
average piano player); if you play more than four 
hours a day, a tune up every three to four months is 
recommended. 


If your organ, or your accordion goes out of tune, 
take it to a repairman and get the offending note fixed. 
In summary, basic care for your keyboard instrument 
entails: 

1. Clean hands and a clean instrument; wash your 
hands before, wash the keyboard after 

2. Tune your instrument regularly; 6 months - aver¬ 
age use, 3 to 4 months for heavy use 

Brass Instruments 

The first rule in caring for any brass instrument is 
Is your mouth clean? Be sure to brush your teeth and 
rinse your mouth if you are going to play the trumpet 
[2] , trombone [3] , or other brass instrument. Food 
particles left in your mouth will foul up the valves 
and slides. It may even cause a restriction of the 
air flow, the instrument to go out of tune, or even 
damage it permanently. 

The second rule is Oil your valves and slides regularly. 
Use the recommended oil for your instrument. This 
will ensure that part movement happens smoothly 
and quickly. 

The third rule is to Polish your instrument after each 
use with a warm, damp cloth. This will help keep it 
from tarnishing from the natural oils in your hand. 
In addition to this, you should use a recommended 
brass polish every month. In summary, basic care for 
your brass instrument entails: 

1. A clean mouth 

2. Oiled valves and slides 

3. Polishing on a regular basis 

Additional Reading 

[1] Tickling the Ivories: Piano for Beginners, Architect 
Press, 1982. 

[2] Trumpeter Lullaby: Caring for Your Horn, County Ecks 
Press, 1985 

[3] Trombone Exercises Emerald Books, 1983 






3 Using the LETTER Doctype 


The LETTER doctype lets you create various types of correspondence such as 
business letters, personal letters, and memos in an 85 x 11 inch format. The 
LETTER doctype has a single design. You process files under this doctype by 
using the LETTER doctype keyword on the DOCUMENT command line. 

The LETTER doctype does not support the full set of VAX DOCUMENT 
global tags. The following tags are not available in the LETTER doctype: 

• <APPENDIX> 

• <CHAPTER> 

• <FRONT_MATTER> 

• <HEAD1> through <HEAD6> 

• < PART-PAGE > 

Even though the LETTER doctype does not support the global numbered 
heading tags ( <headi> , <head2> , and so on), it does support the 
global unnumbered heads ( <SUBHEAD1> and <subhead2> ). See the 
VAX DOCUMENT User Manual, Volume 1 for more information on global 
tags. 

The LETTER doctype-specific tags allow you to label and format the text 
elements of letters and memos. In general, the LETTER doctype tags whose 
tag names are prefixed with "MEMO—" (for example, the <memo_to> tag) 
are used to create memos; the other tags in this doctype are used to create 
letters or headings in either memos or letters. You can use the LETTER 
doctype tags in whatever order you choose. No one tag is restricted to either 
a memo or a letter format. 

Table 3-1 summarizes the tags available in the LETTER doctype. Chapter 10 
contains the reference information on the tags listed in this table. 


Table 3-1 Tags Available in the LETTER Doctype 


Tag Name 

<cc> 

<CCLIST> 

<CHEAD> 

<CLOSING> 


Description 

Labels the name of one person who is to receive a copy of the memo or letter. This 
tag places the heading "cc:" on the left margin, and then places the name of the 
person to the right of this heading on the same line. 

Begins a list of one or more persons' names who are to receive a copy of the memo 
or letter. This tag places the heading"cc:" on the left margin. The <CC> tag is 
used to label each of the names in the list within the context of the <CCLIST> tag. 

Creates an unnumbered centered heading in a memo or letter. 

Labels the closing text of a letter and formats the closing text flush left just to the 
right of the middle of the page. This text is aligned with the output of the <FROM_ 
ADDRESS> tag. This text is typically a closing line such as "Yours Truly," followed 
by the name of the sender. 
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Table 3—1 (Cont.) 

Tags Available in the LETTER Doctype 

Tag Name 

Description 

<DISTLIST> 

Begins a list of people to whom the memo or letter is to be distributed. This list is 
formatted on the left margin beneath a heading of "Distribution:." 

<FROM_ADDRESS> 

Identifies the name and address of the sender of a letter and formats that information 
flush left just to the right of the middle of the page. This text is aligned with the 
output of the <CLOSING> tag. 

<HEAD> 

Creates an unnumbered heading on the left margin of a memo or letter. 

<MEMO_DATE> 

Labels the date of a memo and formats that date flush left near the left margin. This 
tag places the heading "Date." on the left margin. 

<MEMO_FROM> 

Identifies the name and address of the sender of a memo and formats that 
information flush left near the left margin. This tag places the heading "From:" 
on the left margin. 

<MEMO_HEADER> 

Centers the heading "Interoffice Memorandum" on the current line of the output 
page. 

<MEMO_LINE> 

Lets you specify your own information and headings in a format similar to the format 
used by the <MEMO_TO> or <MEMO_FROM> tags. This tag places your heading 
on the left margin and then places the first line of information text to the right of 
that heading on the same line; additional lines of information are formatted under the 
first. 

<MEMO_TO> 

Identifies the name and address of the sender of a memo and formats that 
information flush left near the left margin. This tag places the heading "To:" on 
the left margin. 

<SALUTATION> 

Labels the greeting portion of a letter and formats that greeting on the left margin. 

<SUBJECT> 

Labels the subject of a memo or letter and formats that information flush left near 
the left margin. This tag places the heading "Subject:" on the left margin. The 
subject text is formatted on the same line and to the right of the heading. 

<TO_ADDRESS> 

Identifies the name and address of the receiver of a letter and formats that 
information flush left on the left margin. 


3.1 Sample Uses of the LETTER Doctype Tags 

This section contains two examples of the LETTER doctype tags. The first 
example shows a sample memo and the second example shows a sample 
letter. You may find these sample files useful in understanding how the tags 
all fit together to create memos and letters. 
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3.1.1 A Sample Memo 

The SDML code for a memo is shown first, followed by the output from that 
SDML code. 

<MEMO_HEADER> 

<MEM0_FR0M>(Mr. SmithXCorporate Company Accounting) 

<MEM0_LINE>(Phone\181-1546) 

<MEM0_T0>(Jack Jones\Payroll Accounting) 

<MEM0_DATE>(March 17. 1987) 

<CCLIST> 

<CC>(Jim Walker) 

<CC>(John Beam) 

<CC>(D. M. Bones) 

<ENDCCLIST> 

<CC>(Departmental Distribution) 

<SUBJECT>(Conference Report) 

<P>This conference was hosted by Numbers Inc. in Seattle, Wash., 

March 4 through 7. The goal of the conference was to stimulate the 
development of accounting technology. 

<P>My goals for attending the conference were to learn as much as 
I could about accounting technology and to find out about existing 
products or projects related to accounting methodology. 

<SUBHEAD1>(Summary of Presentations Attended) 

<P> 

Major opening and closing presentations were directed at all conference 
attendees. In between, there were choices between technical sessions and 
general sessions, and I almost always felt a conflict. It was especially 
annoying because there were not many clues as to what the differences were. 
Sometimes technical was way too technical and general was way 
too general. 

<DISTLIST> 

Bert Tom 

Harry Lisa 
Jim Melinda 

Walter Jess 

*A11 Trainees* 

<ENDDISTLIST> 

This example may produce the following output. 
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Sample Memo Created Using Letter Doctype 


INTEROFFICE MEMORANDUM 


From: Mr. Smith 

Corporate Company Accounting 
Phone: 181-1546 

To: Jack Jones 

Payroll Accounting 
Date: March 17, 1987 

cc: Jim Walker 

John Beam 
D. M. Bones 

cc: Departmental Distribution 


Subject: Conference Report 

This conference was hosted by Numbers Inc. in Seattle, Wash., March 4 through 7. The 
goal of the conference was to stimulate the development of accounting technology. 

My goals for attending the conference were to learn as much as I could about accounting 
technology and to find out about existing products or projects related to accounting 
methodology. 

Summary of Presentations Attended 

Major opening and closing presentations were directed at all conference attendees. In 
between, there were choices between technical sessions and general sessions, and I 
almost always felt a conflict. It was especially annoying because there were not many 
clues as to what the differences were. Sometimes technical was way too technical and 
general was way too general. 


DISTRIBUTION: 


Bert Tom 

Harry Lisa 
Jim Melinda 

Walter Jess 
*A11 Trainees* 
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3.1.2 A Sample Letter 

The SDML code for a letter is shown first, followed by the output from that 
SDML code. 


<FROM_ADDRESS>(Harvard UniversttyNCambridge, MA\January 1, 1987, 10:00am EST) 

<T0_ADDRESS>(Carol Jones\World Wide Wickets CoASeattle, WA) 

<SALUTATI0N>(Hi Carol.) 

<P> 

This is an excerpt from a symposium I went to on letter writing. 

I thought you might find it interesting. We really ought to have lunch 
some time. 

<P> 

The excerpt follows: 

<P> 

There are generally two kinds of letters: 

<LIST>(UNNUMBERED) 

<LE> Business letters 
<LE> Personal letters 
<ENDLIST> 

<HEAD>(Writing a Business Letter) 

<P> 

When writing a business letter, form can be very important. 

In many cases, the form of the letter can be nearly as important as the content 
of the letter. 

<CHEAD>(Writing a Letter to Request Information) 

<P> 

A business letter is often used to request information from 
an official source. It is important to specify very clearly what 
information you need, and for what you need it. If your information needs 
are unclear, your request may not be filled. 

<CL0SING>(Best Wishes,\Bob Smith\Chairman, CZZA Committee) 

This example may produce the following output. 
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Sample Letter Created Using Letter Doctype 


Harvard University 

Cambridge, MA 

January 1, 1987, 10:00am EST 


Carol Jones 

World Wide Wickets Co. 

Seattle, WA 

Hi Carol, 

This is an excerpt from a symposium I went to on letter writing. I thought you might 
find it interesting. We really ought to have lunch some time. 

The excerpt follows; 

There are generally two kinds of letters: 

• Business letters 

• Personal letters 

Writing a Business Letter 

When writing a business letter, form can be very important. In many cases, the form of 
the letter can be nearly as important as the content of the letter. 

Writing a Letter to Request Information 

A business letter is often used to request information from an official source. It is 
important to specify very clearly what information you need, and for what you need it. 
If your information needs are unclear, your request may not be filled. 


Best Wishes, 


Bob Smith 

Chairman, CZZA Committee 
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7 Using the REPORT Doctype 


The REPORT doctype lets you create general-purpose documents such as 
reports and formal outlines. The REPORT doctype has two designs. These 
doctype designs are listed by their doctype keyword: 

• REPORT 

Creates an x 11 inch format with unruled numbered and unnumbered 
headings. 

• REPORT.TWOCOL 

Creates the same format as REPORT, but places the text in two columns. 

This doctype accepts the full range of VAX DOCUMENT global tags (see the 
VAX DOCUMENT User Manual, Volume 1 for more information on the global 
tags). The REPORT doctype also provides additional tags that let you perform 
the following functions: 

• Create headings or modify the default attributes of the REPORT doctype. 

• Create signature lines and list author information within the context of 
the global <front_matter> tag 

• Create formal outlines within the context of the < OUTLINE > tag 

You process a file with the REPORT doctype by using the REPORT or 
REPORT.TWOCOL doctype keyword on the VAX DOCUMENT command 
line. See Section 2.2 for information on the special formatting considerations 
of a two-column doctype. 

See VAX DOCUMENT Design Samples for more information on the format of 
the REPORT designs. 

Table 7-1 summarizes the tags available in the REPORT doctype and 
provides a brief description of each tag. Chapter 13 contains the reference 
information on the tags listed in this table. 

Table 7-1 Tags Available in the REPORT Doctype 

Tag Name Description 

Tags Available in the Front Matter 

<AUTHOR> Places the name of an author and up to two additional lines of information 

about the author on the output page. 

<BYLINE> Creates a rule to be used as a signature line, and places the name of the 

signatory beneath the line. 

<SIGNATURES> Begins a listing of signature lines created by the <BYLINE> tag. 

Optionally, you can use this tag to begin the listing of signature lines 
on a new page. 
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Table 7-1 (Cent.) Tags Available in the REPORT Doctype 

Tag Name Description 

Tags Available Throughout the Document 

Creates an unnumbered centered heading. 

Specifies that a new column of output should begin in a two-column 
doctype. 

Modifies the numbering of pages and formal elements in the document. 
Creates an unnumbered heading, which is placed on the left margin. 

Places a heading at the bottom of each page. 

Places a heading at the top of each page. 

Begins a new page and places an unnumbered heading at the top of the 
new page on the left margin. 

Tags Available to Create Outlines 

<LEVEL> Specifies an entry in an outline. 

<OUTLINE> Enables the <LEVEL> and <SHOW_LEVELS> tags and lets you specify a 

title for the outline. 

<SHOW_LEVELS> Emphasizes text within the outline using either bolding or italics. 


<CHEAD> 

< COLUMN > 

<DOCUMENT_ATTRIBUTES> 

<HEAD> 

<RUNNING_FEET> 

<RUNNING_TITLE> 

< SECTION > 


7.1 A Sample Use of the REPORT Doctype Tags 

This section contains an example of the first few pages of a report created 
using the REPORT doctype tags. This report includes a front matter section 
and an outline in the body of the report. Note how the outline and front 
matter tags are used in this example. You may find this sample useful 
in understanding how the tags all fit together to create reports and other 
general-purpose documents. 

The SDML code for the report is shown first, followed by the output from 
that SDML code. 

<FRONT_MATTER> 

<TITLE_PAGE> 

<TITLE>(Equipment Usage in this Company) 

<ABSTRACT> 

This is an internal report on equipment usage during 
the period (May 1986 - November 1986). 

<ENDABSTRACT> 

<AUTH0R>(Thomas A. Smith\Comptroller\Ea8tern Division) 

<SIGNATURES> 

<BYLINE>(T. A. Smith) 

<BYLINE>(John Whorfin\Accounting Consultant) 

<DATE> 

<ENDTITLE_PAGE> 

<ENDFRONT_MATTER> 

<CHAPTER>(Equipment Usage Summary) 

<P>Equipment usage is a very important quantity to monitor. 

If equipment is not used, it is a wasted resource. If equipment is over-used, 
it tends to break sooner, and means that people must wait to use it. If people 
are waiting, they are not being as productive as they might otherwise be. 

<P>The following sections summarize equipment usage in various departments. 
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<HEAD1>(Usage of Official Vehicles) 

<P> 

Official vehicle usage is listed in a separate report C0RP-AUT0-1439u2. 

This report is organized as in the following outline. Note that there are two 
new categories in the report. These categories are italicized in the following 
outline. 

<0UTLINE>(Outline of Report\C0RP-AUT0-1439u2\Motor Vehicle Usage) 

<LEVEL>(l\Four wheeled Vehicles) 

<LEVEL>(2\Cars) 

<LEVEL>(2\Trucks) 

<SHOW_LEVELS>(ITALIC) 

<LEVEL>(3\Heavy trucks) 

<LEVEL>(3\Light trucks (less than 2 ton)) 

<SHOW_LEVELS>(OFF) 

<LEVEL>(2\Vans) 

<ENDOUTLINE> 

This example may produce the following output if processed using the 
REPORT keyword. 
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Sample Output of Report Doctype 


Equipment Usage in this Company 


This is an internal report on equipment usage during the period (May 1986 - November 1986). 


Thomas A. Smith 
Comptroller 
Eastern Division 


T. A. Smith 


John Whorfin—Accounting Consultant 
26-November-1986 
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Sample Output of Report Doctype 


CHAPTER 1 

EQUIPMENT USAGE SUMMARY 


Equipment usage is a very important quantity to monitor. If equipment is not used, it is a wasted 
resource. If equipment is over-used, it tends to break sooner, and means that people must wait to use 
it. If people are waiting, they are not being as productive as they might otherwise be. 

The following sections summarize equipment usage in various departments. 

1.1 Usage of Official Vehicles 

Official vehicle usage is listed in a separate report CORP-AUTO-1439u2. This report is organized as 
in the following outline. Note that there are two new categories in the report. These categories are 
italicized in the following outline. 


Outline of Report 
CORP-AUTO-1439u2 
Motor Vehicle Usage 

I. Four wheeled Vehicles 

A. Cars 

B. Trucks 

1 . Heavy trucks 

2. Light trucks (less than 2 ton) 

C. Vans 
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ARTICLE Doctype Tag Reference 



This chapter provides the reference information on the tags available within 
the ARTICLE doctype. These tags, which allow you to create articles in a 
two-column format, are described alphabetically in this chapter. Chapter 2 
provides a tutorial on how to use these tags. 

The ARTICLE doctype supports all of the VAX DOCUMENT global tags with 
the following exceptions: 

• < CHAPTER > 

• <FRONT_MATTER> 

• < REVISION > , <MARK> , and < UPDATE-RANGE > 

• The MULTIPAGE keyword is not available as an argument to the 

<EXAMPLE_ATTRIBUTES> , < FIGURE-ATTRIBUTES > and <TABLE- 
ATTRIBUTES> tags. This means that formal examples, figures and tables 
are restricted to a length of one page or less. 

See the VAX DOCUMENT User Manual, Volume 1 for more information on 
global tags. See VAX DOCUMENT Design Samples for more information on 
the page layout of ARTICLE doctype. 
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<ABSTRACT> 


<ABSTRACT> 

Creates an article abstract and can also specify a heading for that abstract. 

FORMAT 

<ABSTRACT> [(abstract-heading)] 

ARGUMENTS 

abstract-heading 

Specifies a heading for the abstract. If no heading is specified, none is output. 

related tags 

• The global <abstract> tag 

• <TITLE_SECTION> 

restrictions 

None. 

required 

terminator 

<ENDABSTRACT> 

DESCRIPTION 

The <ABSTRACT> tag is used to create an abstract of an article. This tag can 
be used within the context of the <title_SECTION> tag, or following the 
<TiTLE_SECTiON> tag within the ARTICLE doctype. 

This tag is used in a different manner from the global < ABSTRACT > tag, 
which is used in any doctype other than the ARTICLE doctype within the 
context of the <TITLE_PAGE> tag. 

EXAMPLE 

The following example shows how to create an abstract. It is headed with the 
title "Editor's Note:." 


<ABSTRACT>(Editor’s Note:) 

The following is an excerpt from the paper, 

<qU0TE>(Creating a Lasting Impression.) 

See the bibliography at the end of this article for information on how to 
locate this paper. 

<ENDABSTRACT> 
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<ACKNOWLEDGMENTS> 


<ACKNOWLEDGMENTS> 

Creates an acknowledgments section in an article. 

FORMAT 

<ACKN 0 WLEDG M ENTS > (acknowledgment-text) 

ARGUMENTS 

acknowledgment-text 

Specifies the text of one or more acknowledgments. 

related tags 

• <BACK_NOTES> 

• <REF_NOTES> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <ACKNOWLEDGMENTS> tag outputs the heading "Acknowledgments" 
using the same format as the <back_notes> and <ref_notes> 
tags. The text of the acknowledgment is entered as an argument to the 
<ACKNOWLEDGMENTS> tag. 

The <ACKNOWLEDGMENTS> , <BACK_NOTES> , and <REF_NOTES> tags 
are typically entered at the end of an SDML file to be processed using the 
ARTICLE doctype. 

EXAMPLE 

The following example shows a sample use of the <ACKNOWLEDGMENTS> 
tag. Note how it is used near the end of the SDML file with the < BACK- 
NOTES > and < REF-NOTES > tags. 


<REF_N0TES>(Bibliography) 

<BACK_NOTES>(References) 

<ACKNOWLEDGMENTS>(I am deeply indebted to my doctor for her support in this task.) 
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<AUTHOR> 


<AUTHOR> 

Specifies an author of an article. 

FORMAT 

<AUTHOR > (author-name[ \ optional-information]} 

ARGUMENTS 

author-name 

Specifies the name of the author. If you want the word "By" included with 
the author's name, you must specify it as part of the author-name text. 

optional-information 

Specifies additional optional information about the author. This information 
is formatted below the author's name. This text should be approximately one 
line in length. 

related tags 

• <AUTHOR_ADDR> 

• <AUTHOR_AFF> 

• <AUTHOR_LIST> 

• <VITA> 

restrictions 

None. 

required 

terminator 

None. 


DESCRIPTION Use the <author> tag to place the name of the author in an article. The 

name of the author is given as the first argument to the < AUTHOR > tag; 
additional information about the author can be specified as the second 
argument to the < author > tag. 

The following list includes the other tags that allow you to specify 
information about the author. 

<AUTHOR_ADDR> Specifies an address for the author. 

<AUTHOR_AFF> Specifies the organizational affiliation of the author. 
<AUTHOR_LIST> Lists multiple authors of an article. 

<VITA> Provides information about an author's professional 

history. 

See the appropriate tag description in this chapter for more information on 
any of these tags. 
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<AUTHOR> 


EXAMPLE The following example shows how to use the < AUTHOR > tag in a file 

processed using the ARTICLE doctype. Note how the optional second 
argument to the <AUTHOR> tag is used to give additional information about 
the author. 


<AUTH0R>(By A.B. Roma\Publisher) 
<AUTHOR_AFF>(<emphasis>(Disco Monthly) staff) 
<AUTHOR_ADDR>(Top-Ten Corporation,\ 

5300 Westlake Boulevard,\ 

Los Angeles, California 09945) 
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<AUTHOR_ADDR> 



DESCRIPTION The <AUTHOR_ADDR> tag is used to specify the address of the author of an 

article. The <author_addr> tag outputs one to six lines of text based on 
the number of address-line arguments specified. Each of these arguments is 
placed on a new line on the left margin. 

The following list includes the other tags that allow you to specify 
information about the author. 

<AUTHOR> Specifies an author for an article. 

<AUTHOR_AFF> Specifies the organizational affiliation of the author. 
<AUTFIOR_LIST> Lists multiple authors of an article. 

<VITA> Provides information about an author's professional 

history. 

See the appropriate tag description in this chapter for more information on 
any of these tags. 
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ARTICLE Doctype Tag Reference 

<AUTHOR_ADDR> 


EXAMPLE 


The following example shows how to provide address information about the 
author of an article. 


<AUTH0R>(A.B. Roma) 

<AUTHOR_AFF>(<emphasis>(Disco Monthly) staff) 
<AUTHOR_ADDR>(Top-Ten Corporation,\ 

5300 Westlake Boulevard,\ 

Los Angeles, California 09945) 
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ARTICLE Doctype Tag Reference 

<AUTHOR_AFF> 


<AUTHOR-AFF> 


Specifies information about the organizational affiliation of the author. 


FORMAT < AUTHOR _AFF > (affiliation-information) 


ARGUMENTS affiliation-information 

Specifies information about the affiliation of the author. 


related tags • <author> 

• <AUTHOR_ADDR> 


restrictions None. 


required None. 

terminator 


DESCRIPTION Use the <AUTHOR_aff> tag to describe the professional or educational 

affiliation of the author of an article. This tag is typically entered after the 
<AUTHOR> tag in the SDML file. 

The following list includes the other tags that allow you to specify 
information about the author. 


<AUTHOR> 

<AUTHOR_ADDR> 

<AUTHOR_LIST> 

<VITA> 


Specifies an author for an article. 

Specifies an address for the author. 

Lists multiple authors of an article. 

Provides information about an author's professional 
history. 


See the appropriate tag description in this chapter for more information on 
any of these tags. 


EXAMPLE 


The following example shows how to provide information about the affiliation 
of the author of an article. 


<AUTH0R>(A.B. Roma) 

<AUTHOR_AFF>(<emphasis>(Disco Monthly) staff) 
<AUTHOR_ADDR>(Top-Ten Corporation,\ 

5300 Westlake Boulevard,\ 

Los Angeles, California 09945) 
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ARTICLE Doctype Tag Reference 

<AUTHOR_LIST> 


<AUTHOR_LIST> 


Creates a list of authors for an article with multiple authors. 


FORMAT <AUTHOR_LIST> [(heading-text)] 


ARGUMENTS heading-text 

Provides an introductory heading for a list of authors. A sample heading 
might be "By:." 


related tags 

restrictions 

required 

terminator 


• <AUTHOR> 


None. 


<ENDAUTHOR_LIST> 


DESCRIPTION You can use the <AUTHOR_LlST> tag to place the name of multiple authors 

in an article. You can also optionally specify a heading for the list of authors 
as an argument to the <author_list> tag. The name of each author is 
given as the first argument to the < AUTHOR > tag, and additional information 
about the author can be specified as the second argument to the < AUTHOR > 
tag. 

The following list includes the other tags that allow you to specify 
information about the author. 


<AUTHOR> 

<AUTHOR_ADDR> 

<AUTHOR_AFF> 

<VITA> 


Specifies an author for an article. 

Specifies an address for the author. 

Specifies the organizational affiliation of the author. 

Provides information about an author's professional 
history. 




See the appropriate tag description in this chapter for more information on 
any of these tags. 


EXAMPLE 


The following example shows a list of two authors introduced by the word 
"By:." 


<AUTHOR_LIST>(By:) 

<AUTH0R>(Mary Smith,\User Publications) 
<AUTH0R>(Tom Jones,\Software Engineering) 
<ENDAUTHOR_LIST> 
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<BACK_NOTE> 


<BACK_NOTE> 

Creates a back note entry and a superscript reference number to that 
entry in the article text. 

FORMAT 

<BACK_NOTE> (back-note-text) 

ARGUMENTS 

back-note-text 

Specifies the text to be associated with the back note entry. 

related tags 

• <BACK_NOTES> 

• <REF_NOTE> 

• The global < FOOTNOTE > tag 

restrictions 

The <BACK_NOTE> tag should not be used in the same document as the 
global <FOOTNOTE> tag when the <FOOTNOTE> tag is being used to create 
numbered footnotes, since both tags would place superscript numbers into a 
document, and references to those numbers could be confusing. 

required 

terminator 

None. 

DESCRIPTION 

The <BACK_NOTE> tag allows you to create an entry for a back note (also 
referred to as an "end note") in your document. You enter the <BACK_ 
NOTE> tag in your SDML file wherever you want to provide a back note 
citation. VAX DOCUMENT sequentially numbers each of the back note 
entries and places the appropriate sequential number as a superscript in the 
output file. 

For example, if you want to cite the book Training Seagulls as a back note, 
and this back note is the third in your document, the text where you cited the 
book would appear as follows: 

These techniques are outlined in Training Seagulls 

VAX DOCUMENT collects all the automatically numbered back note entries 
and outputs them together in their sequential order wherever you use the 
<BACK_NOTES> tag. Typically, you will want to use the <BACK_NOTES> 
tag at the end of your article. 
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<BACK_NOTE> 


EXAMPLE The following example shows a reference to a back note and the text of the 

note as it is to appear at the end of the document. The <BACK_NOTES> tag 
at the conclusion of the article causes this note, and any others, to be output. 


As Ms. Roma so clearly stated.<BACK_NOTE>(P.A. Roma, 

<qU0TE> (Computer-Chart Making from the Graphic Editor’s Perspective.) 
<EMPHASIS>(ACM Computer Graphics, SIGGRAPH ’99 Conf. Proc.), 

Vol 45. No. 3, July 1999, pp. 247-253.) 


<BACK_NOTES> 




ARTICLE Doctype Tag Reference 

<BACK_NOTES> 


<BACK_NOTES> 

Causes any accumulated back notes to be output. 



EXAMPLES The following example shows how you can create the heading "References" 

for a list of back notes by coding that heading as an argument to the < BACK- 
NOTES > tag. 


<BACK_NOTES>(References) 

The following example shows how you can create the second level heading 
"Articles" for a list of back notes by coding that heading as an argument to the 
<HEAD2> tag, and placing that tag immediately before the <BACK_NOTES> 
tag. 

<HEAD2>(Articles) 

<BACK_NOTES> 
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ARTICLE Doctype Tag Reference 

<BIBLIOGRAPHY> 


<BIBLIOGRAPHY> 

Begins a bibliography. 

FORMAT 

<BIBLIOGRAPHY> [(heading-text)] 

ARGUMENTS 

heading-text 

Specifies the heading for a bibliography. This heading will appear in the 
format used by <HEAD1> tags in an article with unnumbered heads. By 
default, no heading is output. 

related tags 

• <BIB_ENTRY> 

• <REF_NOTE> 

• <REF_NOTES> 

restrictions 

None. 

required 

terminator 

< ENDBIBLIOGRAPHY> 

DESCRIPTION 

You can use the < bibliography > tag to create a bibliography of related 
reading when you do not use numbered reference notes to reference other 
works in the text of the article. Each of the entries in the bibliography is 
created using the <BIB_ENTRY> tag. You can specify a heading for the 
bibliography either as an argument to the < bibliography > tag or by using 
an unnumbered heading tag immediately before the < BIBLIOGRAPHY > tag. 

If you wish to create numbered reference notes, you should use the < REF- 
NOTE > and < REF-NOTES > tags. 

EXAMPLE 

The following example shows how to format a bibliography using the 
<BIBLIOGRAPHY> tag. 


<BIBLIOGRAPHY>(Bibliography) 

<BIB_ENTRY>(<EMPHASIS>(Molecular Connectivity in Chemistry and Drug Research.) 
Lament B. Kier and Lowell H. Hall. Academic Press, 1983.) 

<BIB_ENTRY>(Arhnheim. Rudolph, <EMPHASIS>(Visual Thinking). 

University of California Press, Berkeley, 1984.) 

<ENDBIBLIOGRAPHY> 
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<BIB_ENTRY> 


<BIB_ENTRY> 

Specifies a single entry in a bibliography. 

FORMAT 

<BIB-.ENTRY> (bibliography-text) 

ARGUMENTS 

bibliography-text 

Specifies the text of the bibliographic entry. 

related tags 

• <BIBLIOGRAPHY> 

restrictions 

Valid only in the context of the <BlBLlOGRAPHY> tag. 

required 

terminator 

None. 

DESCRIPTION 

You can use the <BIB_ENTRY> tag to create a single entry for a bibliography. 
The text of the bibliography entry is passed as an argument to the <BIB_ 
ENTRY> tag. This text can be of any length. 

EXAMPLE 

The following example shows how to use a <BIB_ENTRY> tag to create a 
bibliographic entry within the context of the <BIBLIOGRAPHY> tag. 


<BIBLIOGRAPHY>(Bibliography) 

<BIB_ENTRY>(<EMPHASIS>(Molecular Connectivity in Chemistry and Drug Research.) 
Lament B. Kier and Lowell H. Hall. Academic Press, 1983.) 

<BlB_ENTRY>(Arhnheim, Rudolph. <EMPHAS1S>(Visual Thinking). 

University of California Press, Berkeley, 1984.) 

<ENDB1BL10GRAPHY> 
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<COLUMN> 


<COLUMN> 

Specifies that output should begin in a new column in a two-column 
format. 

FORMAT 

<COLUMN> 

ARGUMENTS 

None. 

related tags 

• The global < FINAL-CLEANUP > tag 

restrictions 

Valid only in a two-column doctype such as REPORT.TWOCOL or ARTICLE. 

required 

terminator 

None. 

DESCRIPTION 

Use the <COLUMN> tag to cause the text immediately following it to be 
started in a new column. If this tag occurs in the left text column, the text 
immediately following it begins in the right text column. If this tag occurs 
in the right text column, the text immediately following it begins in the left 
column of the next page. 

Use the <COLUMN> tag when you always want to begin a new column at 
that point in your text. You can use the COLUMN—BREAK argument to the 
global < FINAL-CLEANUP > tag to also specify a column break; however, this 
should be used only during the final processing of the two-column document. 

See Section 2.2 for more information on improving the formatting of a 
two-column doctype such as ARTICLE. 

EXAMPLE 

The following example shows how to use the < column > tag to begin a new 
text column. In this example, the writer wants the two descriptions to appear 
side by side, one in each column. 







ARTICLE Doctype Tag Reference 
<COLUMN> 


<SUBHEAD1>(Woodwind Instruments) 

<P>Woodwind instruments have the following 
attributes; 

<LIST>(UNNUMBERED) 

<LE>They are often made of wood, hence their name. 

<LE>Musicians create sound using these instruments by causing a reed 
to vibrate. 


<ENDLIST> 

<C0LUMN> 

<SUBHEAD1>(Brass Instruments) 

<P>Brass instruments have the following 
attributes: 

<LIST>(UNNUMBERED) 

<LE>They are often made of brass, hence their name. 
<LE>Musicians create sound using these instruments by 
vibrating (buzzing) their lips into a steel mouthpiece. 


<ENDLIST> 


9-16 



ARTICLE Doctype Tag Reference 

<DOCUMENT_ATTRIBUTES> 


<DOCUMENT_ATTRIBUTES> 

Enables doctype-specific tags that override the default design format of 
the ARTICLE doctype. 

FORMAT 

<DOCUMENT_ATTRIBUTES> 

ARGUMENTS 

None. 

related tags 

None. 

restrictions 

None. 

required 

terminator 

<ENDDOCUMENT_ATTRIBUTES> 


DESCRIPTION The <DOCUMENT_ATTRiBUTES> tag can be used in three doctypes: 


• ARTICLE 

• REPORT 

• SOFTWARE 

The <DOCUMENT_ATTRiBUTES> tag enables a group of tags in each of these 
doctypes that allow you to modify the default format of that doctype. These 
tags are recognized only within the context of the <DOCUMENT_attributes> 
tag. If other VAX DOCUMENT tags occur in this context, they are ignored, as 
if they had occurred within the context of a < COMMENT > tag. 

Typically, you use the < DOCUMENT-ATTRIBUTES > tag at the beginning of an 
input file (or in a file specified using the DOCUMENT /INCLUDE qualifier) 
to alter the default format of a doctype for the processing of that entire file. 

Table 9-1 summarizes the formatting tags enabled by the < DOCUMENT- 
ATTRIBUTES> tag in each of the three supported- doctypes. 
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ARTICLE Doctype Tag Reference 

<DOCUMENT_ATTRIBUTES> 


Table 9—1 Doctype-specific Tags Enabled by the <document_attributes> Tag 


Formatting Tags 

Description 

Tags Enabled in the ARTICLE Doctype 

<SET_HEADINGS> (UNNUMBERED) 
<SET_HEADINGS> (NUMBERED) 

The <SET_HEADINGS> tag specifies whether 
numbered or unnumbered headings are produced 
by the heading-level tags ( <HEAD1> , <HEAD2> , 
and so on). By default, headings are not numbered 
in a document processed using the ARTICLE 
doctype. 


Use the <SET_HEADINGS> (NUMBERED) tag to 
specify that your headings should be numbered. 

Tags Enabled in the REPORT Doctype 


<SET_PAGE_NUMBERING> (BY_CHAPTER) The <SET_PAGE_NUMBERING> tag specifies 

<SET_PAGE_NUMBERING> (SEQUENTIAL) how pages are to be numbered in a document 


processed using the REPORT doctype. Pages are 
numbered sequentially by default. 

If the BY_CHAPTER argument is used, the pages 
are numbered by chapter. For example, the second 
page in Chapter 3 would be numbered 3-2. If the 
BY_CHAPTER argument is used in a document 
that contains no chapters, the page numbering is 
sequential. 

The SEQUENTIAL argument specifies that the 
pages should be numbered sequentially, as they 
are by default. 

<SET_FORMAL_ELEMENT_NUMBERING> (BY_CHAPTER) The <SET_FORMAL_ELEMENT_NUMBERING> tag 

<SET_FORMAI_ELEMENT_NUMBERING> (SEQUENTIAL) specifies how formal tables, figures, and examples 

are to be numbered in a document processed using 
the REPORT doctype. By default, formal tables, 
figures, and examples are numbered sequentially. 

The BY—CHAPTER argument indicates that formal 
elements are to be numbered using the chapter 
prefix; for example, the first formal table in 
Chapter 4 would be numbered as Table 4-1. 

The SEQUENTIAL argument indicates that 
formal elements are to be numbered sequentially 
throughout the document; for example, the eighth 
formal table in the document, regardless of what 
chapter it occurs in, would be numbered as 
Table 8. 

If the BY_CHAPTER argument is used in 
a document that contains no chapters, 

VAX DOCUMENT uses the default sequential 
formal element numbering. 
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ARTICLE Doctype Tag Reference 

< DOCUM ENT_ATTRI BUTES> 


Table 9-1 (Cent.) Doctype-specific Tags Enabled by the <document_attributes> Tag 


Formatting Tags 

Description 

Tags Enabled in the SOFTWARE Doctype 


<SET_RUNNING_TITLES> (BY_HEADONE) 

The <SET_RUNNING_TITLES> tag specifies 
that the running title at the top of each page is 
composed of two lines: the first line is the title 
of the chapter, and the second line is the heading 
text of the current <HEAD1> tag. Note that the 
argument BY_HEADONE is required. 

By default, the chapter title is used as a single-line 
running title. 


EXAMPLE In the following example of a file to be processed under the ARTICLE 

doctype, numbered headings are specified using the <SET_HEADINGS> tag 
with the NUMBERED argument. This will cause any subsequent heading tags 
( <HEADl> , <HEAD2> and SO on) to be numbered. 

<DOCUMENT_ATTRIBUTES> 

<SET_HEADINGS>(NUMBERED) 

<ENDDOCUMENT_ATTRIBUTES> 
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ARTICLE Doctype Tag Reference 

<QUOTATION> 


< QUOTATION > 

Begins a quotation in which the spacing is retained and the text is not filled 
or justified. 

FORMAT 

< QUOTATION > 

ARGUMENTS 

None. 

related tags 

• The global <code_example> tag 

• The global <sample_text> tag 

restrictions 

None. 

required 

terminator 

<ENDQUOTATION> 

DESCRIPTION 

Use the < QUOTATION > tag to format a quotation in which you want the 
spacing to be retained and the text to not be filled or justified. 

The < QUOTATION > tag differs from the global < CODE-EXAMPLE > tag in that 
the text of the quotation is not set in a monospaced font. It allows you to 
quote poetry or passages of text that you do not want formatted. 

For long, block-style quotations, you should use the global <SAMPLE_text> 
tag. 

EXAMPLE 

The following example shows how you can use the <QUOTATlON> tag to set 
off a quotation in text and have the spacing retained. 


It is often instructive to remember the words of our founder: 
<QU0TATI0N> 

It is better to try again 
than to fail; 

And better still to succeed. 

<ENDqUOTATION> 


9-20 






ARTICLE Doctype Tag Reference 

<REF_NOTE> 


<REF_NOTE> 

Specifies the text of a reference note, and creates a bracketed reference 
number in the article text. 

FORMAT 

<REF_NOTE> (text-of-note[\ symbol-name]) 

ARGUMENTS 

text-of-note 

Specifies the text of the reference note. 

symbol-name 

Specifies the symbolic name of the note. Specify this argument when you 
need to refer to the same note more than once in the same article. Subsequent 
referrals to the same note are made by referring to this symbol name with the 
global < REFERENCE > tag. 

The symbol-name argument can be any text string of 31 characters or less 
without spaces. This text must contain only the letters A through Z, the 
numbers 0 through 9 and the underscore (_) character. The symbol-name 
may not begin with an underscore character. 

related tags 

• <BACK_NOTE> 

• <BIBLIOGRAPHY> 

• <REF_NOTES> 

• The global < FOOTNOTE > tag 

• The global <reference> tag 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the <REF_N0TE> tag to create a reference note. Place the <REF_NOTE> 
tag in the SDML file at the point at which you are referencing text for which 
you want to provide the note. This tag is replaced in the output file by a 
number in brackets that corresponds to the number assigned to the note text; 
for example, [4]. 

Use the <REF_N0TES> tag to cause the text of this note and any other 
reference notes you have created using the <REF_NOTE> tag to be output. 
The <REF_NOTES> tag is typically placed at the end of the SDML file. 

To reference a source that you have already referenced using the <REF_ 
NOTE> tag, you need to specify the symbol-name argument to that <REF_ 
NOTE> tag and use the global <REFERENCE> tag to refer to that symbol. 
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ARTICLE Doctype Tag Reference 

<REF_NOTE> 


Use the <bibliography> tag to create a bibliography that is not tied to 
references in the text of an article. 


EXAMPLE The following example shows how to use the <REF_NOTE> tag both for 

a single reference and for two references to the same source. Note how 
the second reference to the Hopkins and Johnson article is made using the 
<REFERENCE> tag. 

These notes and any others would be output by the <rEF_notes> tag that 
occurs at the end of the article. 

Hopkins and Johnson (1968) 

<REF_N0TE>(A.A Hopkins and B.B. Johnson,<QU0TE>(An Eye for an Eye,) Proceedings 
of the American Journal of Comparative Biology, 163:1145-1152.\EYE_ARTICLE) 
noted the preponderance of short cones in type A subjects. 

The research of J.Dobbs (1972) 

<REF_N0TE>(J. Dobbs,<quote>(Cones in Type A and B Subjects), Proceedings 
of the American Journal of Comparative Biology, 167:201-227.) 
corroborated this observation. 

<P> 

In 1978 the research of Hopkins and Johnson (1968) <REFERENCE>(EYE_ARTICLE), 
was shown to have been misleading. 


<REF_N0TES> 
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ARTICLE Doctype Tag Reference 

<REF_NOTES> 


<REF_NOTES> 

Causes all accumulated reference notes to be output. 

FORMAT 

<REF_NOTES> [(heading-text)] 

ARGUMENTS 

heading-text 

Specifies a heading for the reference notes. This heading has the default 
heading format used by <HEADl> tags in an article with unnumbered heads. 

If you do not specify the heading-text argument, no heading is output. You 
can specify your own heading, with the heading tag ( <HEADl> , <HEAD2> 
and so on) that is appropriate to your document. 

related tags 

• <REE_NOTE> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the <REE_NOTES> tag to output a list of all the references you created 
using the <REE_NOTE> tag. These references are numbered and correspond 
to the number placed in your document by the <REF_NOTE> tag (for 
example, [4]). Typically, the <REF_NOTES> tag is placed at the end of 
the SDML file so that the accumulated references appear at the end of the 
article. 

Use the <bibliography> tag to create a bibliography that is not tied to 
references in the text of an article. 

EXAMPLES 

The following example shows how you can create a list of references with the 
heading "References." 


<REF_N0TES>(Ref erenc es) 


The following example shows how you can use a heading tag as an 
alternative heading for the list of references. In this example, the <HEAD2> 
tag was used. 

2 <HEAD2>(References) 

<REF_N0TES> 
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ARTICLE Doctype Tag Reference 

<RUNNING_FEET> 


<RUNNING 

i_FEET> 

Creates a single line heading at the bottom of each page. 

FORMAT 

<RUNNING_FEET> (title-text) 

ARGUMENTS 

title-text 

Specifies the text to be used as a running heading at the foot of the page. 

related tags 

• < RUNNING-TITLE > 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the <RUNNING_FEET> tag to place a heading at the bottom of every 
page. This heading is called a "footer" because it appears at the foot of 
the page. When the same footer is used for several pages, the footers are 
collectively called "running feet." 

This tag accepts one argument that is the text heading that appears at the 
bottom of the page. This text is output exactly as entered, including spacing 
and capitalization. 

Use the <running_title> tag to create a heading at the top of the 
page. See the reference description of the <RUNNING_TITLE> tag for more 
information on that tag. 

EXAMPLE 

The following example shows how to use the <RUNNING_FEET> tag to place 
the heading "Getting the Piece of Paper" at the bottom of each page. The 
running footer will be output exactly as entered. 


<RUNNING_FEET>(Getting the Piece of Paper) 

<HEAD2>(Getting the Piece of Paper) 

<P> 

You can buy clean paper in most major supermarkets, department stores, 
and hardware stores. You should try to get ruled paper so that 
your letter will be neat and easy to read. 
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ARTICLE Doctype Tag Reference 

<RUNNING_TITLE> 



DESCRIPTION Use the < RUNNING-TITLE > tag to specify a one- or two-line title at the top 

of the page. Use the FIRST-PAGE argument to the <RUNNING_TITLE> tag to 
begin the title lines on the first page of output, rather than on the page after 
the current page as is the default. 

Use the OFF argument to disable any existing running titles created using the 
<RUNNING_TITLE> tag. These titles will then be disabled for the page on 
which this tag occurs and on any subsequent pages. 

Use the <running_feet> tag to create a heading that appears at the bottom 
of the page. See the reference description of the < RUNNING_FEET> tag for 
more information on that tag. 
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ARTICLE Doctype Tag Reference 

<RUNNING_TITLE> 


EXAMPLES The following examples show how to use the <running_title> tag to 

create titles and how to disable them. 

The following example shows how to use the <RUNNING_TITLE> tag to 
create the two line running title "An E. B. Bartz Course:" and "Writing Quality 
Correspondence." Note that because the FIRST-PAGE argument is used, the 
two-line running title will appear at the top of the first page. 

Q <RUNNING_TITLE>(An E. B. Bartz Course:\Writing Quality Correspondence\FIRST_PAGE) 

<HEAD>(How to Write a Letter) 

<P> 

The first thing that you should do in writing a letter is to get 
a clean piece of paper and a well-sharpened pencil. 

The following example shows how you can disable a running title by using 
the OFF argument to the <RUNNING_TITLE> tag. 

2 <C0MMENT>(turn off running titles for the following example page) 

<RUNNING_TITLE>(OFF) 

<HEAD>(An Example of a Letter) 
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ARTICLE Doctype Tag Reference 

<SOURCE_NOTE> 


<SOURCE 

_NOTE> 

Provides information pertaining to the original source of information for an 
article. 

FORMAT 

<SOURCE_>NOTE> (source-text) 

ARGUMENTS 

source-text 

Specifies the text that describes the source of the article. The text can be any 
length and can include any tags not listed in the restrictions section. The 
source text is positioned at the bottom of the column of output in which the 
tag is specified. 

related tags 

• <AUTHOR> 

• <VITA> 

restrictions 

The following tags should not be used as part of the source note text: 
<CODE_EXAMPLE> , <EXAMPLE> , <FIGURE> , <FORMAT> , <HEAD1> 
through <HEAD6> , < INTERACTIVE > , <MATH> , or .<NOTE> . 

required 

terminator 

None. 

DESCRIPTION 

Typically, information provided in the < SOURCE _NOTE> tag is placed either 
at the beginning of the first column on the first page of an article or at the 
end of the last column on the last page. You should place the <SOURCE_ 
NOTE> tag in your SDML file to correspond to where you want the output to 
appear. 

If you want the text to appear on the first page, specify the tag following the 
<AUTHOR> tag. If you want the text to appear on the last page, specify the 
tag at the end of the SDML file. 

E)(AMPLE 

The following example shows how to create a note describing the original 
source of an article. Note that the global <line> tag is used to produce 
a line beginning with the copyright symbol to indicate the copyright date. 

The copyright symbol is created by using the global <MCS> tag with the 
argument COPYRIGHT. 


<S0URCE_N0TE>(Reprinted from <EMPHASIS>(Visible Discs.) Volume V, 
Number 3, Summer 1971. c/o The Top-Ten Museum of Art. Cleveland. 
Ohio, U.S.A., 44106 
<LINE> 

<MCS>(COPYRIGHT) 1971 by <EMPHASIS>(Visible Discs.)) 
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<SUBTITLE> 


<SUBTITLE> 

Specifies a subtitle for an article. 

FORMAT 

<SUBTITLE> (title-line-1 [\title-line-2[\ title-line-3]]) 

ARGUMENTS 

title-line-n 

Specifies up to three lines of text for subtitle of an article. The text of each 
argument is centered on a new line of output. 

related tags 

• < TITLE > 

• < TITLE-SECTION > 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the <SUBTITLE> tag to create a subordinate title for an article that has 
up to three separate lines. Each of the subtitle lines is centered in the column 
in which the tag occurs (typically the first column). Use the <TITLE> tag to 
create a main title for an article. 

If you want the subtitle (or title) to span both columns of the article, 
you should use the <TlTLE_SECTlON> tag in your SDML file before the 
<SUBTITLE> (or <TITLE> ) tag. 

EXAMPLE 

The following example illustrates an article that begins with a main title 
followed by a subtitle that will span both columns. Note that the <AUTHOR> 
tag occurs outside of the context of the < TITLE-SECTION > tag so it will not 
span both columns in the output. 


<TITLE_SECTION> 

<TITLE>(FILE PROCESSING) 

<SUBTITLE>(CONCEPTS AND INSTRUCTIONS) 
<ENDTITLE_SECTION> 

<AUTHOR>(A.B. Roma\Contributing Editor) 
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ARTICLE Doctype Tag Reference 

<TITLE> 


<TITLE> 

Specifies the main title line for an article. 

FORMAT 

< TITLE > (title-line-1 [\ title-line-2[\ title-line-3]]) 

ARGUMENTS 

title-line-n 

Specifies up to three lines of text for the title of the article. The text of each 
argument is centered on a new line of output. 

related tags 

• < SUBTITLE > 

• <TITLE_SECTION> 

\ 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the < TITLE > tag to create a main title for an article that has up to three 
separate lines. Each of the title lines is centered in the column in which the 
tag occurs (typically the first column). Use the < SUBTITLE > tag to create a 
subordinate title for an article. 

If you want the title (or subtitle) to span both columns of the article, use 
the < TITLE-SECTION > tag in your SDML file before the < title > (or 
<SUBTITLE> ) tag. 

EXAMPLE 

<TITLE_SECTION> 

The following example illustrates an article that begins with a main title 
followed by a subtitle that spans both columns. Note that the <AUTHOR> 
tag occurs outside of the context of the <TITLE_SECTI0N> tag so it will not 
span both columns in the output. 


<TITLE>(FILE PROCESSING\USING THE CALL INTERFACE) 
<SUBTITLE>(CONCEPTS AND INSTRUCTIONS) 
<ENDTITLE_SECTION> 

<AUTH0R>(A.B. Roma\Contributing Editor) 
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ARTICLE Doctype Tag Reference 

<TITLE_SECTION> 



ARGUMENTS None. 

related tags • <subtitle> 

• < TITLE > 

restrictions None. 

required <endtitle_section> 

terminator 


DESCRIPTION Use the <TlTLE_SECTlON> tag to create a section at the beginning of an 

article in which you want a title, subtitle, or other information to span the 
full page. If the <TITLE> or <SUBTITLE> tag is used in the context of the 
< TITLE-SECTION > tag, the typeface that is output by those tags will be 
larger than the typeface that is output outside of the context of the < TITLE- 
SECTION> tag. 

If you do not use the < title-SECTION > tag, any titles, subtitles, or additional 
information is output in the appropriate column and does not span the full 
page. 


EXAMPLES In the following example, the < TITLE > and < SUBTITLE > tags are specified 

within the context of the <TITLE_SECTI0N> tag. The <AUTHOR> tag 
appears after the <ENDTlTLE_SECTiON> , so it will be formatted in the first 
column of the article. 

Q <TITLE_SECTION> 

<TITLE>(Optical Discs) 

<SUBTITLE>(The New Documentation Frontier) 

<ENDTITLE_SECTION> 

<AUTH0R>(A.B. Roma) 

In the following example, the < title > and < SUBTITLE > tags are used 
without the <TlTLE-SECTlON> tag so the title and subtitle text will be set in 
the first column with the author information. 

2 <TITLE>(Optical Discs) 

<SUBTITLE>(The New Documentation Frontier) 

<AUTH0R>(A. B. Roma) 
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ARTICLE Doctype Tag Reference 

<VITA> 


<VITA> 

Provides information about the author's professional history. 

FORMAT 

<VITA> (vita-text) 

ARGUMENTS 

vita-text 

Specifies information describing the professional history of the author. The 
text can be any length and can include any tags that are not listed in the 
restrictions section. The vita text is positioned at the bottom of the column of 
output in which the tag is specified. 

related tags 

• <AUTHOR> 

• < SOURCE-NOTE > 

restrictions 

The following tags should not be used as part of the vita text: <C0DE_ 
EXAMPLE>, <EXAMPLE>, <FIGURE> , <FORMAT> , <HEAD1> through 
<HEAD6> , <INTERACTIVE> , <MATH> , or <NOTE> . 

required 

terminator 

None. 

DESCRIPTION 

Use the <VITA> tag to describe the professional history of an article's author. 
Typically, information provided in the <V1TA> tag is placed either at the 
beginning of the first column of the first page of an article, or at the end of 
the last column on the last page. You should place the <VITA> tag in your 
SDML file to correspond to where you want the output to appear. 

If you want the text to appear on the first page, specify the <VITA> tag 
following the < AUTHOR > tag. If you want the text to appear on the last 
page, specify the <VITA> tag at the end of the SDML file. 

The following list includes the other tags that allow you to specify 
information about the author. 

<AUTHOR> Specifies an author for an article. 

<AUTHOR_ADDR> Specifies an address for the author. 

<AUTHOR_AFF> Specifies the organizational affiliation of the author. 

<AUTHOR_LIST> Lists multiple authors of an article. 

See the appropriate tag description in this chapter for more information on 
any of these tags. 
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<VITA> 


EXAMPLE The following example illustrates how to create a description of the author to 

accompany the <AUTHOR> tag. This coding positions the text at the bottom 
of the first column of the first page of the article. 

<AUTH0R>(A.B. Roma) 

<VITA>(A.B. Roma is program director for 

information processing and distribution for the Top-Ten Corporation. 

She has published numerous magazine articles.) 
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4 Using the MANUAL Doctype 


The MANUAL doctype lets you create users' manuals in one of three designs: 

• MANUAL.GUIDE 

Creates a users' manual in a 7 x 9 inch format with numbered headings. 
This design is intended for chapter-oriented tutorial material. 

• MANUAL.PRIMER 

Creates a users' manual in a 7 x 9 inch format with unnumbered headings. 
This design is intended for chapter-oriented primer material. 

• MANUAL.REFERENCE 

Creates a users' manual in an 8^ x 11 inch format with numbered 
headings. This design is intended for reference material. 

The MANUAL doctype provides no doctype-specific tags, but accepts the 
full range of VAX DOCUMENT global tags. See the VAX DOCUMENT User 
Manual, Volume 1 for more information on global tags. 

You process a file with the MANUAL doctype by using one of the doctype 
keywords in the preceding list on the DOCUMENT command line. The 
following example shows how to process a file named MYMANUAL.SDML 
with the MANUAL doctype to create a reference manual. 

$ DOCUMENT mymanual MANUAL.REFERENCE LN03 

See VAX DOCUMENT Design Samples for more information on the format of 
the MANUAL designs. 


4.1 A Sample of the MANUAL Doctype 

This section contains an example of the first few pages of a hardware manual 
created using the MANUAL.REFERENCE doctype. This manual sample 
includes a title page and some numbered headings and a table in the body of 
the manual. You may find this sample useful in understanding how global 
tags can be used in the MANUAL doctype to create various kinds of manuals. 

The SDML code for the manual is shown first, followed by the output from 
that SDML code. 

<FRONT_MATTER> 

<TITLE_PAGE> 

<TITLE>(Series III Overthruster\User Manual) 

<ABSTRACT> 

This book describes the Series III Overthruster, the Series III 
manual-override mode and the Overthruster monitor utilities. 

<ENDABSTRACT> 

<ENDTITLE_PAGE> 

<ENDFRONT_MATTER> 


Using the MANUAL Doctype 


<CHAPTER>(Introduction to the Overthruster\INTRO_CHAP) 

<P> 

The Series III Overthruster is an intelligent mass thrust device, 
designed to deliver controlled thrust from a ZX-300 type drive unit. 

The Series III family provides enhanced data collection and control 
utilities far superior to those present in the Series II. 

<HEAD1>(Series III Overthruster Models) 

<p> 

The Series III Overthruster family has three models. 

<REFERENCE>(M0DEL_TAB) lists these models and the salient 
features of each. 

<TABLE>(Comparison of Series III Overthruster Models\MODEL_TAB) 

<TABLE_SETUP>(4\25\10\10) 

<TABLE_HEADS>(Feature\<SPAN>(3\LEFT)Models\ \ ) 

<TABLE_HEADS>( \SIII-030\SIII-050\SIII-070) 

<TABLE_ROW>(Data Channels Supported\2\4\4) 

<TABLE_R0W>(I/0 Control Processor \A-L35\J19\J19) 

<TABLE_R0W>(Drive Unit\ZX-301\ZX-301\ZX-310A) 

<TABLE_R0W>(Power Source\TY-100\TY-100A \TY-200) 

<TABLE_R0W>(Control Memory\128Kb\128Kb\512Kb) 

<TABLE_ROW>(Data MemoryX — \ — \512Kb) 

<ENDTABLE> 

<HEAD1>(Series III Overthruster Functional Description) 

<p> 

The Series III Overthruster is an intelligent mass thrust device in accordance 
with the DS8 architecture. 


This example may produce the following output if processed using the 
MANUAL doctype keyword. 



Using the MANUAL Doctype 


Sample Output of Manual Doctype 


Series III Overthruster 
User Manual 


This book describes the Series III Overthruster, the Series III manual-override mode and 
the Overthruster monitor utilities. 
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Sample Output of Manual Doctype 

Chapter 1 

Introduction to the Overthruster 

The Series III Overthruster is an intelligent mass thrust device, designed to deliver controlled 
thrust from a ZX-300 type drive unit. The Series III family provides enhanced data collection 
and control utilities far superior to those present in the Series II. 

1.1 Series III Overthruster Models 

The Series III Overthruster family has three models. Table 1-1 lists these models and the salient 
features of each. 

Table 1-1: Comparison of Series III Overthruster Models 


Feature 

Models 

SIII-O30 

SIII-O50 

SIII-O70 

Data Channels Supported 

2 

4 

4 

I/O Control Processor 

A-L35 

J19 

J19 

Drive Unit 

ZX-301 

ZX-301 

ZX-310A 

Power Source 

TY-100 

TY-IOOA 

TY-200 

Control Memory 

128Kb 

128Kb 

512Kb 

Data Memory 

— 

— 

512Kb 


1.2 Series III Overthruster Functional Description 

The Series III Overthruster is an intelligent mass thrust device in accordance with the DS8 
architecture. 









5 Using the MILSPEC Doctype 


The MILSPEC doctype lets you create standard military specifications 
in accordance with the United States Department of Defense Military 
Specification Standard MIL-STD-490A, published June 4, 1985. 

The MILSPEC doctype has a single design. You process files under this 
doctype by using the MILSPEC doctype keyword on the DOCUMENT 
command line. 

This doctype accepts the full range of VAX DOCUMENT global tags, with the 
exception of the <part> and <part_page> tags (see the VAX DOCUMENT 
User Manual, Volume 1 for more information on global tags). 

It also provides doctype-specific tags that let you create a title page in 
accordance with the MIL-STD-490A standard, and a tag that allows you 
to override the default appendix numbering used by VAX DOCUMENT. 
Chapter 11 provides the reference information on these tags. 

Table 5-1 briefly describes the doctype-specific tags available in the MILSPEC 
doctype. 

Table 5-1 Tags Available in the MILSPEC Doctype 

Tag Name Description 

<SET_APPENDIX_NUMBER> Overrides the default appendix Roman number assigned to an appendix by 

VAX DOCUMENT. 

Begins a two-column listing of signature lines on the title page and places 
a heading above each list. Each row of signature lines is created using the 
<SIGNATURE-LINE> tag within the context of the <SIGNATURE_LIST> tag. 

Creates up to two rules on a line (one in each signature column) and places 
a name below each rule; each rule is used as a signatory line for the person 
listed below it. 

<SPECIFICATION_INFO> Creates a listing of information about the specification document on the title 

page and creates a two-line running heading listing the specification number 
and date for the rest of the document. 

<SPEC_TITLE> Creates a title with up to seven centered lines on the title page. 

<SUBTITLE> Creates a subtitle with up to seven centered lines on the title page. 

VAX DOCUMENT provides a template SDML file for general usage of 
the MIL-STD-490A format. It also provides 24 template SDML files 
for documents that conform to the Department of Defense standard 
DOD-STD-2167 for Data Item Descriptions (DID) published June 4, 1985. 
Data item descriptions are MIL-STD-490A documents that are specialized for 
a particular kind of information. The exact form of each data item description 
is specified by DOD-STD-2167. 

You can use these files to create military specifications. If you have VAX 
Language-Sensitive Editor Version 2.0 (LSE) installed on your system, 
you can use that editor to access the LSE templates for the data item 
description documents and expand the appropriate placeholders. See the 


<SIGNATURE_LIST> 

<SIGNATURE_LINE> 
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VAX DOCUMENT User Manual, Volume 1 for more information on using LSE 
with VAX DOCUMENT. 

Each template file contains all the headings, titles, and so on required 
by the DOD-STD-2167 specification for that document. The template 
input files contain comments that guide you in placing your information 
into the file. Table 5-2 lists the data item description templates files that 
VAX DOCUMENT provides. 

Documents produced using the MILSPEC doctype conform to the 
MIL-STD-490A specification and have the following general attributes: 

• Pages, formal figures, and formal tables are numbered sequentially 
throughout the document and are not numbered by chapter, section, or 
appendix. 

• Paragraphs are numbered using the global numbered heading tags 

( <HEADl> , <HEAD2> , and SO on) to create the Arabic numerals. A 
period (.) is automatically placed at the end of the numbered paragraph 
headings. 

• Formal tables are numbered using Roman numerals. 

• The global < preface > tag automatically generates a preface section 
heading of "Foreword" rather than "Preface." All other VAX DOCUMENT 
doctypes use the heading "Preface." 

• The table of contents begins on page ii rather than on page iii. All other 
VAX DOCUMENT doctypes that support the automatic creation of tables 
of contents begin the table of contents on page iii. 

• Appendixes are numbered using Roman numerals. Sections and 
paragraphs within an appendix are numbered in Arabic numbers that 
correspond to the appendix number multiplied by 10. For example, in 
Appendix II, the first paragraph would be paragraph 20, and the second 
paragraph would be 20.1. 

See VAX DOCUMENT Design Samples for additional information on the 
format of the MILSPEC design. 


5.1 Writing a Document According to MIL-STD-490A 

You can create a document in accordance with MIL-STD-490A either by 
copying the template file MILSPEC—SAMPLE.SDML from the directory 
DOC$TEMPLATES into your work directory and then editing it to insert your 
text, or by creating your own file. There are comments in the template file to 
guide you in its use. If you create your own new file, you may still want to 
look at the template SDML input file as a guide. 

You can use the MILSPEC doctype to create documents that conform to 
MIL-STD-490A by tagging them in the following manner: 

• Create the required cover page for the document using the <SPEC_ 
TITLE> and <SPECiFiCATiON_iNFO> tags within the context of the 
global <TITLE_PAGE> tag. The <SPEC_title> tag creates a title for 
the document and the <specification_info> tag places additional 
information on the cover page of the document, as well as setting the 
running headings for the rest of the document (including the table of 
contents). 
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• Create major sections (such as Section 1, "Scope/') in your document 
using the global <chapter> tag. Each <chapter> tag that has 
paragraph text immediately following it should have a <P> tag placed 
between the heading and the text for correct formatting. Chapters that 
contain no pertinent information should be coded with the <CHAPTER> 
tag, complete with the appropriate title text and the symbol name 
argument. Such chapters should contain only the following standard 
disclaimer paragraph as specified in MIL-STD-490A. 

This section is not applicable to this 
specification. 

Because the disclaimer text does not vary from use to use, you may want 
to symbolize it using the global <DEFlNE_SYMBOL> tag as follows: 

<DEFINE_SYMBOL>(This section is not applicable to this specification.\na_text) 

You could then use the global <reference> tag to include this text as 
follows: 

<cominent>(This section must be included for DID 80031 dociunents, 
but requires no specification details.) 

<CHAPTER>(Qualification Requirements\qualifications_sec) 

<P> 

<REFERENCE>(NA.TEXT) 

• Create the numbered paragraphs within each major section using the 
appropriate global numbered heading tags ( <headi> , <heaD2> , and 
so on). Each heading tag that has paragraph text immediately following 
it should have a <P> tag placed between the heading and the text for 
correct formatting. The MILSPEC doctype automatically inserts a period 
at the end of all titled numbered headings. 

If you need to cross reference numbered paragraphs within your 
document, you should specify them using the <REFERENCE> tag with the 
VALUE argument so that the default text "Section" is not automatically 
output before the paragraph number. 


5.2 Writing Data Item Description Documents 

VAX DOCUMENT provides 24 template files for data item description (DID) 
documents and a general military specification template file, which can be 
customized for other documents. The framework for each of the supported 
DID specifications is supplied in the template files so that all you need supply 
is the text for your particular document. All required tags, including section 
and paragraph headings, are provided in the document template. 

Each template file is a collection of individual element files coded for a 
specific DID or military document. These files are concatenated into a single 
file to simplify usage and storage. When you use one of these files, separate 
it into several files, one file for each major section. 

Each section of the template input file is labeled with comments that contain 
directions for its use. Placing each major section in a separate file makes it 
easier to maintain your document, and lets you use the book building features 
of VAX DOCUMENT. You then list these files in a profile file and process the 
profile list through a book build. 
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For example, if you were to use the file MILSPEC_DID_80025.SDML, you 
would place each of the six major sections in a separate file, and also place 
the front matter section and the symbol definition section in separate files. 
Each of these files would be placed in your document when you process book 
build profile file. 

The following is a list of steps you should follow to use the MILSPEC 
template files. 

1 Select the template you want by referring to Table 5-2. If the template 
you want is not listed, use the file MILSPEC_SAMPLE.SDML as the 
basis for creating your own template. You may want to read through the 
template to make sure it is the one you want. 

2 Copy the template file into your working directory. Do not modify the 
VAX DOCUMENT templates in DOC$TEMPLATES. Other users of 
VAX DOCUMENT may also want to use them. 

3 Separate the templated file into separate files, placing each major section 
(begun using the <CHAPTER> tag) in a separate file. The front matter 
(begun with the <FRONT_MATTER> tag) and the symbol definitions (the 
<DEFiNE_SYMBOL> and < DEFINE_BOOK-NAME > tags) should also be 
placed in separate files. 

References to symbols created using the <DEFlNE_SYMBOL> tag occur in 
each template file. Comments in the template file identify which symbols 
are used by all the templates and which symbols are used only in that 
particular template. 

You will need to modify the text arguments to the <define_SYMBOL> 
tags so that the proper text (such as your product's name) is automatically 
inserted into the template. 

4 Create a book building profile that lists each of the major sections and 
the front matter file as book elements. These book elements can then be 
built into a single book by VAX DOCUMENT. You may want to include 
the <contents_file> and < index _file> tags in your profile file to 
automatically include your table of contents and index files into the final 
book. 

The profile should not include the file that contains the symbol definitions 
in it. These symbol definitions should be included into your document by 
specifying the symbol definitions file as an argument to the DOCUMENT 
/SYMBOLS qualifier when you process your profile. 

The following is a sample book building profile for a military specification 
document. See how the <contents_file> and < index _file> tags are 
used to automatically include the table of contents and index files for the 
document. 

<PR0FILE> 

<ELEMENT>(frontmatter.sdml) 

<CONTENTS_FILE> 

<ELEMENT>(scopechap.sdml) 

<ELEMENT>(secondchap.sdml) 

<ELEMENT>(thlrdchap.sdml) 

<ELEMENT>(fourthchap.sdml) 

<ELEMENT>(fifthchap.sdml) 

<ELEMENT>(noteschap.sdml) 

<ELEMENT>(firstapx.sdml) 

<INDEX_FILE> 

<ENDPROFILE> 
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If you have a large book element, or a book element that contains sections 
that change a great deal, you may want to separate the book element into 
several files called book subelements that are included into the book 
element file using the global < include > tag. The following sample 
shows the book element file THIRDCHAP.SDML that includes several 
book subelement files. 

<CHAPTER>(Testing ResultsXtest.results.chap) 

<INCLUDE>(testing_intro. sdinl) 

<INCLUDE>(testl_results.sdml) 

<INCLUDE>(test2_results.sdml) 

<INCLUDE>(test3_results.sdml) 

<INCLUDE>(test4_results.sdml) 

<INCLUDE>(test5_results.sdml) 

<INCLUDE>(testing_conclusions.sdml) 

Each of these book subelements can be processed individually and have 
all cross references correctly resolved after a bookbuild of the entire 
book has taken place (the book build process creates the XREF cross 
reference file that the subelement accesses to resolve the cross references). 
See the VAX DOCUMENT User Manual, Volume 1 for more information 
about creating and using book build profiles, symbol definitions files, and 
processing book subelements. 

5 Enter the appropriate information for your document into each of the 
major sections of the template input file. 

Table 5-2 lists the data item descriptions for which VAX DOCUMENT 

provides templated SDML files. The names of the template files correspond 

to their data item description document number. 


Table 5-2 MILSPEC Doctype Data Item Description Templates 


Data Item 

Description 

Number 

Template 

Description 

Template Files Located 
in the Directory 
DOCSTEMPLATES 

None. 

Sample template for any document 
conforming to MIL-STD-490A 

MILSPEC-SAMPLE.SDML 

DI-CMAN-80008 
AMSC No. N3584 

System/Segment Specification 

MILSPEC_DID_80008.SDML 

DI-MCCR-80009 

AMSC No. N3585 

Software Configuration Management 
Plan 

MILSPEC_DID_80009.SDML 

DI-MCCR-80010 

AMSC No. N3586 

Software Quality Evaluation Plan 

MILSPEC_DID_80010.SDML 

DI-MCCR-80011 

AMSC No. N3587 

Software Standards and Procedures 
Manual 

MILSPEC_DID_80011.SDML 

DI-MCCR-80012 

AMSC No. N3588 

Software Top Level Design Document 

MILSPEC_DID_80012.SDML 

DI-MCCR-80013 

AMSC No. N3589 

Version Description Document 

MILSPEC_DID_80013.SDML 

DI-MCCR-80014 

AMSC No. N3590 

Software Test Plan 

MILSPEC_DID_80014.SDML 

DI-MCCR-80015 

AMSC No. N3591 

Software Test Description 

MILSPEC_DID_80015 .SDML 


5-5 





Using the MILSPEC Doctype 


Table 5-2 (Cont.) MILSPEC Doctype Data Item Description Templates 


Data Item 

Description 

Number 

Template 

Description 

Template Files Located 
in the Directory 

DOC$TEM PLATES 

DI-MCCR-80016 

AMSC No. N3592 

Software Test Procedure 

MILSPEC_DID_80016.SDML 

DI-MCCR-80017 

AMSC No. N3593 

Software Test Report 

MILSPEC_DID_80017.SDML 

DI-MCCR-80018 

AMSC No. N3594 

Computer System Operator's Manual 

MILSPEC_DID_80018.SDML 

DI-MCCR-80019 

AMSC No. N3595 

Software User's Manual 

MILSPEC_DID_80019.SDML 

DI-MCCR-80020 

AMSC No. N3596 

Computer System Diagnostic Manual 

MILSPEC_DID_80020. SDML 

DI-MCCR-80021 

AMSC No. N3597 

Software Programmer's Manual 

MILSPEC_DID_80021 .SDML 

DI-MCCR-80022 

AMSC No. N3598 

Firmware Support Manual 

MILSPEC_DID_80022.SDML 

DI-MCCR-80023 

AMSC No. N3599 

Operational Concept Document 

MILSPEC_DID_80023.SDML 

DI-MCCR-80024 

AMSC No. N3600 

Computer Resources Integrated 

Support Document 

MILSPEC_DID_80024.SDML 

DI-MCCR-80025 

AMSC No. N3601 

Software Requirements Specification 

MILSPEC_DID_80025.SDML 

DI-MCCR-80026 

AMSC No. N3602 

Interface Requirements Specification 

MILSPEC_DID_80026.SDML 

DI-MCCR-80027 

AMSC No. N3603 

Interface Design Document 

MILSPEC_DID_80027.SDML 

DI-MCCR-80028 

AMSC No. N3604 

Data Base Design Document 

MILSPEC_DID_80028.SDML 

DI-MCCR-80029 

AMSC No. N3605 

Software Product Specification 

MILSPEC_DID_80029.SDML 

DI-MCCR-80030 

AMSC No. N3606 

Software Development Plan 

MILSPEC_DID_80030.SDML 

Dl-MCCR-80031 

AMSC No. N3607 

Software Detail Design Document 

MILSPEC_DID_80031 .SDML 


5.3 A Sample Use of the MILSPEC Doctype Tags 

This section contains a sample of the first few pages of a specification created 
using the MILSPEC doctype. This sample includes the title page of the 
specification and the first page of text after the title page. The text page 
illustrates numbered paragraphs and tables created using the MILSPEC 
doctype. 
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Note how the <specification_info> tag is used to create the running 
heads, which contain the date and specification number. Also note that all 
major paragraphs are numbered by using one of the numbered heading tags 
such as <HEAD1> and <head2> . The SDML code for the specification is 
shown first, followed by the output from that SDML code. 


<FRONT_MATTER> 

<TITLE_PAGE> 

<SPECIFICATI0N_INF0>(12345B\al42-b4\<DATE>\Part I of Three Parts) 

<SPEC_TITLE>(Preliminary Development Specification 
\For the Overthmster Monitor System 
\Series (Series Configuration Number) 

\0rder Number (Approved Order Number)) 

<SUBTITLE>(Submitted Under\Contract AOOOOO—11—A—2222) 

<SIGNATURE_LIST>(Authenticated by:\Approved by:) 

<SIGNATURE_LINE>(Procurer\Program Manager) 

<SIGNATURE_LINE>(Date\Technical Director) 

<SIGNATURE_LINE>(\Consultant) 

<ENDSIGNATURE_LIST> 

<ENDTITLE_PAGE> 

<ENDFRONT_MATTER> 

<CHAPTER>(Scope\first_sec) 

<HEAD1>(Scope\scope_head) 

<P> 

This document establishes all specifications for the design and 

production of the Overthruster Monitor System (USN-122-233x) by our Corporation. 

<HEAD1>(Purpose\purpose_sec) 

<P> 

The purpose of this document is to specify all design and production 
dimensions of the Overthruster Monitor System. This will ensure that all 
essential requirements are met and that all concerns are addressed. 

<HEAD2>(Primary Purpose\Primary_purpose_sec) 

<P> 

The primary purpose is to enrich the quality dimension of our product. 

<HEAD3>(Secondary Purpose\secondary_purpose_sec) 

<P> 

The secondary purpose is to create a corporate strategy for the product that 
encompasses the goals established in <REFERENCE>(primary_purpose_sec\VALUE). 

<P> 

<ELLIPSIS> 

<P> 

Production of the Overthruster Monitor System will necessitate a reorganization 
of our current production strategy. In order to produce the projected 
quantities of the Overthruster Monitor System we will have to make the changes 
summarized in <REFERENCE>(0MS_tab). 

<TABLE>(Overthruster Monitor System <oparen>OMS<cparen> Production Line Impact\OMS_tab) 
<TABLE_ATTRIBUTES>(WIDE) 

<TABLE_SETUP>(2\18) 

<TABLE_HEADS>(Production<LINE>Line Name\Production<LINE>Line Modification) 

<TABLE_R0W>(Alpha<LINE> (System Units) 

\1007, conversion from Series II OMS production to Series III OMS production.) 
<TABLE_ROW>(Beta<LINE> (Unit Stands) 

\Increase production 307, and designate 507, of 

that production for the Overthruster Monitor System sales.) 

<TABLE_R0W>(Gamma<LINE> (Model I Power Supplies) 

\Phase out production over 6 month time frame. 

Will be modified to produce the new Model IIA Power Supply.) 

<TABLE_ROW>(Omega<LINE> (Model IIA Power Supplies) 

\Increase production by 357, until Gamma comes on-line in 6 months.) 

<ENDTABLE> 


This example may produce the following output if processed using the 
MILSPEC doctype keyword. 
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Sample Output of Milspec Doctype 


12345B 

al42-b4 

22 June 1987 

Part I of Three Parts 


Preliminary Development Specification 
For the Overthruster Monitor System 
Series (Series Configuration Number) 
Order Number (Approved Order Number) 

Submitted Under 
Contract AOOOOO-ll-A-2222 

Authenticated by: Approved by: 


Procurer 


Program Manager 


Date 


Technical Director 


Consultant 
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Sample Output of Milspec Doctype 


12345B 
22 June 1987 


1. SCOPE 

1.1 Scope. This document establishes all specifications for the design and production of the 
Overthruster Monitor System (USN-122-233x) by our Corporation. 

1.2 Purpose. The purpose of this document is to specify all design and production dimensions of 
the Overthruster Monitor System. This will ensure that all essential requirements are met and that all 
concerns are addressed. 

1.2.1 Primary Purpose. The primary purpose is to enrich the quality dimension of our product. 

1.2.1.1 Secondary Purpose. The secondary purpose is to create a corporate strategy for the product 
that encompasses the goals established in 1.2.1. 


Production of the Overthruster Monitor System will necessitate a reorganization of our current production 
strategy. In order to produce the projected quantities of the Overthruster Monitor System we will have 
to make the changes summarized in Table 1. 


Table 1. Overthruster Monitor System (OMS) Production Line Impact 


Production Production 

Line Name Line Modification 


Alpha 

(System Units) 

Beta 

(Unit Stands) 

Gamma 

(Model I Power Supplies) 
Omega 

(Model IIA Power Supplies) 


100% conversion from Series II OMS production to Series III OMS 
production. 

Increase production 30% and designate 50% of that production for the 
Overthruster Monitor System sales. 

Phase out production over 6 month time frame. Will be modified to 
produce the new Model IIA Power Supply. 

Increase production by 35% until Gamma comes on-line in 6 months. 
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The OVERHEADS doctype lets you create pages with large bold text that 
copies well and is easy to see. These pages can then be used to create 
transparencies or 35mm photograph mounts for use on an overhead projector 
or similar display device. 

The OVERHEADS doctype has two designs. These doctype designs are listed 
by their doctype keyword: 

• OVERHEADS 

Creates a page with an 8^ x 11 inch format. This design can be used 
to create slides that fit on overhead projectors, or figures that fit into an 
8^ X 11 inch notebook. 

• OVERHEADS.35MM 

Creates a 6^ x 5| inch format that can be 
photographic reduction. 

The OVERHEADS doctype supports all of the 
with the following exceptions: 

• <APPENDIX> 

• < CHAPTER > 

• <CONTENTS_FILE> 

• <FRONT_MATTER> 

• <GLOSSARY> 

• <HEAD1> through <HEAD6> 

• <INDEX_FILE> 

• <PART> 

• <PART_PAGE> 

• < PROFILE > 

See the VAX DOCUMENT User Manual, Volume 1 for more information on 
global tags. 

Table 6-1 briefly describes the doctype-specific tags available in the 
OVERHEADS doctype. Chapter 12 contains the reference information on 
the tags listed in this table. 


used to create 35mm slides by 
VAX DOCUMENT global tags 
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Table 6-1 Tags Available in the OVERHEADS Doctype 


Tag Name 

Description 

<AUTHOR_INFO> 

Specifies from one to four lines of information about the slide presentation. This 
information is placed on the right side of the slide toward the bottom edge. 

<AUTO_NUMBER> 

Automatically numbers slides that occur in the same file. Additionally, you can 
specify an argument to this tag that places a text string at the beginning of each 
slide number, for example, "Vacation-1." 

<INTRO_SUBTITLE> 

Creates a secondary title of one to to four lines on an introductory slide. Typically, 
titles created using the <INTRO_SUBTITLE> tag occupy a large amount of space on 
the slide. 

<INTRO_TITLE> 

Creates a main title of one to four lines on an introductory slide. Typically, titles 
created using the <INTRO_TITLE> tag occupy a large amount of space on the slide. 

<RUNNING_FEET> 

Places a heading at the bottom right of the current slide and all subsequent slides. 

If the <RUNNING_FEET> tag is used with the <AUTO_NUMBER> tag, the slide is 
numbered on the bottom right, and the text string is placed on the bottom left. 

<RUNNING_TITLE> 

Places a title at the top of all subsequent slides. 

<SLIDE> 

Begins a new overhead slide. Optionally, you can use this tag to specify text that is 
to be placed at the bottom of the slide. 

<SUBTITLE> 

Creates a secondary title with one to four title lines for a nonintroductory slide. The 
title lines produced by the <SUBTITLE> tag are output in a smaller type face with 
less space between lines than the title lines produced by the <INTRO_SUBTITLE> 
tag. 

Modifies the size of the type face used in a topic, table, or list on a single slide. 

<TEXT_SIZE> 

<TITLE> 

Creates a main title with one to four title lines for a nonintroductory slide. The title 
lines produced by the <TITLE> tag are output in the same type face with less space 
between lines than the title lines produced by the <INTR0_TITLE> tag. 

<TOPIC> 

Specifies a line of topic text for a slide. This text begins at the left margin and is in 
a smaller type font than the font used by the <TITLE> tag. 


You process a file with the OVERHEADS doctype by using one of the doctype 
keywords in the preceding list on the DOCUMENT command line. The 
following example shows how to process a file named MYGRAPHIC.SDML 
with the OVERHEADS.35MM doctype to create a 35mm slide mount. 

$ DOCUMENT mygraphic OVERHEADS.35MM LN03 

You will probably want to use the LN03_LASER_PRINTER or POSTSCRIPT 
destinations when you create your overheads, because these destinations 
provide better quality output than the LINE-PRINTER destination. You may 
want to make xerographic copies of your printed VAX DOCUMENT files and 
use these copies to create the overhead transparencies. Xerographic copies 
of laser printer output often reproduce better than the original laser printer 
output. 

See VAX DOCUMENT Design Samples for more information on the format of 
the OVERHEADS designs. 
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6.1 Sample Use of the OVERHEADS Doctype Tags 

This section contains an example of two slides produced using the 
OVERHEADS doctype tags. The first slide is an introductory slide for a 
slide presentation. Note how the tags used to create this slide are particularly 
appropriate (for example the <lNTRO_TITLE> and <lNTRO_SUBTlTLE> tags 
are used). You may find this sample useful in understanding how the tags all 
fit together to create overhead slides. 

The SDML code for the two slides is shown first, followed by the output from 
that SDML code. 

<SLIDE>(Presented 3/8/86) 

<AUTO_NUMBER>(DMS) 

<RUNNING_TITLE>(Pets Are People Too) 

<RUNNING_FEET>(Pet selection seminar) 

<INTRO_TITLE>(CHOOSING THE\RIGHT PET F0R\Y0U) 

<INTRO_SUBTITLE>(A Seminar on\Pet Selection) 

<AUTH0R_INF0>(D. M. SmithWeterinarian) 

<SLIDE> 

<TITLE>(Heart RatesMn Pets and Wild Mammals) 

<SUBTITLE>(Physiological Data \on Selected Mammals) 

<TOPIC>(Nondomesticated Mammal Heart Rates) 

<TABLE> 

<table_attributes>(KEEP) 

<table_setup>(3\19\16) 

<table_heads>(Common Name\Weight\Heart Rate) 

<table_row>(European hedgehog\500-700 g.\246) 

<table_row>(Gray shrew\3-4 g.\782) 

<table_row>(Least chipmunk\40 g.\684) 

<table_row>(Gray squirrel\500-600 g.\390) 

<table_row>(Harbor porpoise\170 kg.\40-110) 

<table_row>(Mink\0.7-1.4 kg.\272) 

<table_row>(Harbor seal\20-25 kg.\18-25) 

<endtable> 

This example may produce the following output if processed using the 
OVERHEADS keyword. 
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Sample Output of Overhead Doctype 

CHOOSING THE 
RIGHT PET FOR 
YOU 

A Seminar on 
Pet Selection 


D. M. Smith 
Veterinarian 


Pet selection seminar 


Presented 3/8/86 
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Sample Output of Overhead Doctype 
Pets Are People Too 

Heart Rates 

In Pets and Wild Mammals 

Physiological Data 
on Selected Mammals 


Nondomesticated Mammal Heart Rates 

Table 1: Heart Rates of Selected Mammals 


Common Name 

Weight 

Heart Rate 

European hedgehog 

500-700 g. 

246 

Gray shrew 

3-4 g. 

782 

Least chipmunk 

40 g. 

684 

Gray squirrel 

500-600 g. 

390 

Harbor porpoise 

170 kg. 

40-110 

Mink 

0.7-1.4 kg. 

272 

Harbor seal 

20-25 kg. 

18-25 


Pet selection seminar 


DMS 1 
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The SOFTWARE doctype provides various formats, tags, and tag templates 
for those who wish to describe computer software. It is equally well-suited to 
describing tutorial or reference information and contains tags customized for 
describing software in either of these formats. 

The SOFTWARE doctype lets you create documents in one of six designs: 

• SOFTWARE.BROCHURE 

Creates a brochure in a 7 x 9 inch format with unnumbered headings. 

• SOFTWARE.GUIDE 

Creates a users' guide in a 7 x 9 inch format with numbered headings. 

• SOFTWARE.HANDBOOK 

Creates a handbook in a 7 x 9 inch format with numbered headings. 

• SOFTWARE.POCKET-REFERENCE 

Creates a pocket reference in a 5^ x 7 inch format with numbered 
headings. 

• SOFTWARE.REFERENCE 

Creates a reference manual in an 8^ x 11 inch format with numbered 
headings. 

• SOFTWARE.SPECIFICATION 

Creates a specification in an 8| x 11 inch format with numbered headings. 

The SOFTWARE doctype accepts the full range of VAX DOCUMENT global 
tags. See the VAX DOCUMENT User Manual, Volume 1 for more information 
on global tags. It also enables a large number of tags specially suited for 
describing various kinds of software. Chapter 14 contains the reference 
information on these tags. 

You process a file with the SOFTWARE doctype by using one of the doctype 
keywords in the preceding list on the DOCUMENT command line. The 
following example shows how to process a file named MYSOFTWARE.SDML 
with the SOFTWARE.GUIDE doctype. 

$ DOCUMENT mysoftware SOFTWARE.GUIDE LN03 

See VAX DOCUMENT Design Samples for more information on the format of 
each of the SOFTWARE designs. 

The SOFTWARE doctype contains doctype-specific tags that can be used 
throughout the SOFTWARE doctype designs and doctype-specific tags 
that can be used only within the context of the reference templates in the 
SOFTWARE doctype. 
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The SOFTWARE doctype-specific tags are available only in the SOFTWARE 
doctype and allow you to create the basic writing elements that you need to 
describe computer software, such as terminal keys and keypads, command 
qualifiers and parameters, and programming language code fragments. See 
Section 8.1 for detailed information on these tags. 

The reference template tags are doctype-specific tags that are available only 
in the reference templates of the SOFTWARE doctype. With these tags, 
you can specify the format of a software command, the restrictions on such 
commands, prompts used within an interactive environment, and so on. See 
Section 8.2 for detailed information on these tags. 


8.1 SOFTWARE Doctype-Specific Tags 

The SOFTWARE doctype-specific tags allow you to describe software 
elements in structured reference material and in less structured tutorial 
material. Using these tags, you can describe the following: 

• Terminal keys and keypads 

• Code fragments and their results 

• Software messages 

• Software arguments, parameters, and qualifiers 

• Interactive terminal sessions 


8.1.1 Documenting Terminal Keys and Keypads 

The SOFTWARE doctype contains several tags that allow you to accurately 
represent terminal keys, keypads, and key names both in text and in 
examples. These tags fall into two groups: 

• Tags that describe keys that can be used throughout the SOFTWARE 
doctype 

• Tags used to create keypad diagrams that can be used only within the 
context of the <keypad_section> tag in the SOFTWARE doctype 


8 . 1 . 1.1 


Describing Individual Keys 

Use the following tags to label and describe certain keys and key sequences 
that appear on keyboards and keypads. 


<CPOS> 

<DELETE_KEY> 

<KEY> 

<KEY_NAME> 

<KEY-SEQUENCE> 

<GRAPHIC> 


Creates a typographically distinct marking for the cursor 
position within an example. 

Creates a special character that represents the DELETE 
key used on keyboards. 

Creates a label for a key from the keyboard or keypad. 
Creates a label for a key name. 

Creates a section in which you can depict a sequence of 
keys. 

Creates a specially formatted character out of the two 
characters specified as arguments. 
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Using the <CPOS> Tag 

Use the <CPOS> tag to mark the position of the cursor in a terminal example. 
The cursor is depicted as the underline character. The following example 
shows how the <CPOS> tag can be used. 

<p> 

Correct the directory specification to <QUOTE>([TEXTFILES]) by 
moving the cursor to the misspelled letter in the directory 
specification as in the following example: 

<DISPLAY> 

$ COPY ABC.TXT [T<CPOS>(R)XTFILES] 

<ENDDISPLAY> 

This example may produce the following output. 

Correct the directory specification to "[TEXTFILES]" by 
moving the cursor to the misspelled letter in the directory 
specification as in the following example: 

$ COPY ABC.TXT [TmFILES] 

Using the <delete_key> Tag 

Use the <delete_key> tag to create the character used on most terminal 
and typewriter keyboards for the DELETE key. The following example shows 
how the <DELETE_KEY> tag can be used. 

<p> 

Press the DELETE key (<DELETE_KEY>) to delete a character. 

This example may produce the following output. 

Press the DELETE key (<3]) to delete a character. 

Using the <graphic> Tag 

Use the <graphic> tag to create special graphic characters that appear 
on the terminal screen. The <GRAPHic> tag accepts two characters as 
arguments and formats them next to each other with the second character 
formatted slightly below the first character. This tag allows you to create 
representations of the linefeed and formfeed characters as well as other 
similarly-formatted characters. 

The following example shows how the <GRAPHIC> tag can be used. 

<p> 

Two special characters that will appear in your editing session 
are the linefeed (<GRAPHIC>(L\F)) and the formfeed (<GRAPHIC>(F\F)) 
characters. 

This example may produce the following output; 

Two special characters that will appear in your editing session 
are the linefeed (Ip ) and the formfeed ) characters. 

Using the <key_name> Tag 

Use the <key_name> tag to differentiate the name of a key from the other 
output in an example or in text. 

The following example shows how the <key_name> tag can be used. 

<p> 

Press the <KEY_NAME>(HELP) or the <KEY_NAME>(DO) key for more information. 
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This example may produce the following output. 

Press the HELP or the DO key for more information. 

Using the <key> Tag 

Use the <KEY> tag to represent a terminal key either in text or in an 
example. The <KEY> tag accepts a key-label argument, which specifies 
the name of the key. 

If you want to represent a terminal key in text, you can use the TEXT 
keyword argument to the <KEY> tag to place angle brackets before and 
after the key label. Use the BOX keyword argument to the <key> tag to 
place the key label in a box that resembles a key to represent a terminal key 
in an example. If neither the TEXT nor the BOX keyword is specified, the 
default format is BOX. 

The following example shows how the <KEY> tag can be coded as it would 
appear in text using the TEXT keyword argument, and as it would appear in 
an example using the BOX keyword argument. 

Note that the <key> tag is used within the context of the <key_sequence> 
tag. See the description of the <key_sequence> tag in this section for more 
information on that tag. 

<p> 

You should now press the <KEY>(RETURN\TEXT) key to insert a line. 

<KEY_SEQUENCE> 

<KEY>(RETURN\BOX) 

<ENDKEY_SEqUENCE> 

This example may produce the following output. 

You should now press the <RETURN> key to insert a line. 

[return I 

Using the <key_sequence> Tag 

Use the <key_sequence> tag to give an example of a sequence of keys. For 
example, you might wish to describe the sequence of keys needed to exit a 
text editor. 

The <key_sequence> tag enables the <key_plus> and the <key_type> 
tags to make creating such key sequences easier. The <KEY_PLUS> tag 
creates a plus sign (+) between two keys, and the <key_type> tag lets you 
associate a key sequence with some textual information, such as a terminal 
type. In addition to these two tags, the <key> tag can also be used within 
the context of the <key_sequence> tag. 

When the <key> tag is used within a key sequence, it accepts an additional 
argument, which lets you place two key labels rather than one inside a box or 
angle brackets. When two key labels are used, they are stacked together with 
the first argument placed on the top. This extra argument makes it possible 
to specify keys that use two stacked words as their label, such as the "Next 
Screen" key. 

The following code fragment contains a series of key examples within a 
<KEY-SEQUENCE > section. Note that the <key> tag is used in two contexts 
in this example. Within the context of the <KEY_SEQUENCE> tag the <KEY> 
tag accepts two key label arguments. Outside of the context of the <KEY_ 
SEQUENCE> tag the <KEY> tag accepts only a single-key label argument. 
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Note also that the first <key> tag is specified with no keyword argument so 
that the default BOX is used, the second <KEY> tag explicitly uses the BOX 
keyword to specify BOX formatting, and in the third <KEY> tag, the TEXT 
keyword argument is used. 


<p> 

You would use the following sequence of keys: 

<KEY_SEQUENCE> 

<KEY>(Next\Screen) <KEY_PLUS> <KEY>(PF3\B0X) 

<ENDKEY_SEqUENCE> 

<P> 

These keys are not associated with the <key>(WHITE\TEXT) keys. 


This example may produce the following output: 

You would use the following sequence of keys: 


Next 

Screen 


PF3 


These keys are not associated with the < WHITE > keys. 


8.1.1.2 Describing Keypads and Keypad Keys 

A keypad is a group of keys separate from those on the typing keyboard. 
These keys are typically used for special applications, such as editing, data 
entry, or cursor movement. The following diagram shows such a keypad. 


□□□ 


□□□ 


□□□ 


□□□ 


LJU 



Showing keypads and keypad keys is often difficult because it involves 
preparing artwork by hand. Within the SOFTWARE doctype, you can 
prepare your own keypad and keypad key diagrams by using the < KEYPAD- 
SECTiON> tag and the tags it enables. 

The < KEYPAD-SECTION > tag begins a section in which keypad diagrams can 
to be created and described. This section is terminated by the <ENDKEYPAD_ 
SECTION > tag. Each keypad or portion of a keypad is created using the 
following tags: 

• < KEYPAD > 

Begins a single illustration of a keypad or a portion of a keypad, and 
optionally allows a title to be placed on each illustration. A keypad 
cannot be more than four columns wide or more than five rows long. 
This tag is terminated by the <ENDKEYPAD> tag. Note that more than 
one keypad can be created in a keypad section using the < keypad > and 
<ENDKEYPAD> tags to create each keypad. 

• <KEYPAD-ROW> 

Creates a four-column keypad row for all but the bottom row of the 
keypad. 
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• <KEYPAD_ENDROW> 

Creates a special three-column keypad row for the larger keys on the 
bottom row of the keypad. 

If you use the DISPLAY keyword argument with the < KEYPAD > tag, you can 
specify arguments to the <keypad_row> and <keypad_endrow> tags that 
will place text on the appropriate key in the keypad diagram. 

If you do not use the DISPLAY keyword, you can specify only one of three 
keywords as the arguments to the <keypad_row> and <keypad_endrow> 
tags. 

The <KEYPAD_ROW> and <keypad_endrow> tags accept the same 
keyword arguments, which allow you to specify whether a key should be 
drawn, and whether a key that is drawn should be shaded in. If no keyword 
argument is specified for a particular keypad column, the key is drawn and it 
is left open (not shaded in). 

The following keywords are accepted by the <KEYPAD_ROW> and <keypad_ 
ENDROW> tags: 

• OPEN — Specifies that the key in that column is to be left blank. OPEN 
is the default. 

• CLOSED —Specifies that the key in that column is to be shaded in. 

• NONE — Specifies that no key should be drawn in that column. 

The following examples show how to use the keypad section tags to create 
various keypad diagrams. The first example shows a complete keypad with 
one key shaded in. 

<KEYPAD_SECTION> 

<KEYPAD>(A Complete Keypad Diagram) 

<KEYPAD_ROW>( \ \ \ ) 

<KEYPAD_ROW>( \ \ \ ) 

<KEYPAD_ROW>( \ \CL0SED\ ) 

<KEYPAD_ROW>( \ \ \N0NE ) 

<KEYPAD_ENDROW>( \ \ ) 

<ENDKEYPAD> 

<ENDKEYPAD_SEC.TION> 

This example may produce the following output: 

A Complete Keypad Diagram 


□□□ 


□□□ 




□□□ 



The following example shows a single line from the previous keypad diagram: 

<KEYPAD_SECTION> 

<KEYPAD>(A Single Keypad Line) 

<KEYPAD_ROW>( \ \CL0SED\ ) 

<ENDKEYPAD> 

<ENDKEYPAD_SECTION> 

This example may produce the following output: 
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A Single Keypad Line 

The following example shows the complete keypad with some keys 
eliminated from the diagram. You can use the NONE keyword argument 
to eliminate keys from the keypad diagram. 

<KEYPAD_SECTION> 

<KEYPAD>(An Irregular Keypad) 

<KEYPAD_ROW>( \ \ \N0NE) 

<KEYPAD_ROW>( \CL0SED\ \N0NE) 

<KEYPAD_R0W>(N0NE\ \N0NE\N0NE) 

<KEYPAD_ROW>(CL0SED\ \CL0SED\N0NE) 

<ENDKEYPAD> 

<ENDKEYPAD_SECTION> 

This example may produce the following output: 

An Irregular Keypad 

□□□ 

□ 

The following example shows how the DISPLAY keyword argument to the 
< KEYPAD > tag allows you to specify text as the arguments to the < KEYPAD- 
ROW> and <keypad_endrow> tags. 

<KEYPAD_SECTION> 

<KEYPAD>(The Editing Keypad With Key Labels\DISPLAY) 

<KEYPAD_ROW>(PF1\PF2\PF3\PF4) 

<KEYPAD_ROW>(7\8\9\-) 

<KEYPAD_ROW>(4\5\6\.) 

<KEYPAD_R0W>(1\2\3\ ) 

<KEYPAD_ENDROW>(0\.\ENTER) 

<ENDKEYPAD> 

<ENDKEYPAD_SECTION> 

This example may produce the following output: 

The Editing Keypad With Key Labels 


PF1 

PF2 

PF3 

PF4 

7 

8 

9 

- 

4 

5 

6 

' 

1 

2 

3 

ENTER 

0 
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<KEYPAD_SECTION> 

<KEYPAD>(The Editing Keypad With Key Labels and Blacked-in Keys\DISPLAY) 
<KEYPAD_R0W>(CL0SED\PF2\PF3\PF4) 

<KEYPAD_ROW>(7\8\9\-) 

<KEYPAD_ROW>(CL0SED\5\6\.) 

<KEYPAD_R0W>(1\2\3\ ) 

<KEYPAD_ENDROW>(0\.\ENTER) 

<ENDKEYPAD> 

<ENDKEYPAD_SECTION> 

This example may produce the following output: 

The Editing Keypad With Key Labels and Blacked-in Keys 


1 

PF2 

PF3 

PF4 

7 

8 

9 

- 

■ 

5 

6 

' 

1 

2 

3 

ENTER 

0 



8.1.2 Documenting Code Fragments 

There are three tags available in the SOFTWARE doctype that let you describe 
software code fragments. These tags let you create syntax statements, 
emphasize arguments, and create samples of screen displays. 

<DISPLAY> Simulates a screen display. 

<SYNTAX> Formats text on the page exactly as entered to allow correct 
positioning of code or syntax statements. 

<ARGUMENT> Emphasizes arguments to functions, procedures, or tags within 
text using an altered text font (such as bold face or italic). 

Using the <display> tag 

The < DISPLAY > tag lets you create an example that simulates a screen 
display. This example is terminated by the <enddisplay> tag. The 
<DISPLAY> tag accepts one of two keyword arguments. 

The WIDE keyword argument extends the display format into the left margin. 
The KEEP keyword argument specifies that the entire display example should 
be placed on the next page if it does not fit on the existing page. This 
argument is used to prevent unnecessary page breaks in display examples. 

The following example shows how you can use the < DISPLAY > tag to 
simulate a screen display. This example was coded using the WIDE argument 
due to the width of the example. Note that all the spacing in the display is 
retained as it was entered. 
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<DISPLAY>(WIDE) 


VAX/VMS V4.4 on node XXXXXX 6- 

-NOV- 

■1986 17:43 

: 18.03 Uptime 

0 02:08: 

56 

Pid Process Name 

State 

Pri 

I/O 


CPU 

Page fits Ph 

.Mem 

20400080 NULL 

COM 

0 

0 

0 

00:15:46.03 

0 

0 

20400081 SWAPPER 

HIB 

16 

0 

0 

00:00:19.74 

0 

0 

20400085 ERRFMT 

HIB 

7 

157 

0 

00:00:01.32 

67 

104 

20400086 CACHE_SERVER 

HIB 

16 

6 

0 

00:00:00.12 

57 

92 

20400087 CLUSTER.SERVER 

HIB 

10 

14 

0 

00:00:00.61 

109 

257 

20400088 OPCOM 

LEF 

7 

126 

0 

00:00:01.06 

332 

77 

20400089 JOB.CONTROL 

HIB 

8 

2081 

0 

00:00:22.95 

190 

322 

2040008A CONFIGURE 

HIB 

9 

19 

0 

00:00:00.18 

99 

136 

20400092 SYMBIONT.OOOl 

HIB 

6 

312 

0 

00:00:06.34 

2886 

63 


<ENDDISPLAY> 

This example may produce the following output. 


VAX/VMS V4.4 on node XXXXXX 6-N0V-1986 17:43:18.03 Uptime 0 02:08:56 


Pid 

Process Name 

State 

Pri 

I/O 


CPU 

Page fits 

Ph.Mem 

20400080 

NULL 

COM 

0 

0 

0 

00:15:46.03 

0 

0 

20400081 

SWAPPER 

HIB 

16 

0 

0 

00:00:19.74 

0 

0 

20400085 

ERRFMT 

HIB 

7 

157 

0 

00:00:01.32 

67 

104 

20400086 

CACHE.SERVER 

HIB 

16 

6 

0 

00:00:00.12 

57 

92 

20400087 

CLUSTER.SERVER 

HIB 

10 

14 

0 

00:00:00.61 

109 

257 

20400088 

OPCOM 

LEF 

7 

126 

0 

00:00:01.06 

332 

77 

20400089 

JOB.CONTROL 

HIB 

8 

2081 

0 

00:00:22.95 

190 

322 

2040008A 

CONFIGURE 

HIB 

9 

19 

0 

00:00:00.18 

99 

136 

20400092 

SYMBIONT.OOOl 

HIB 

6 

312 

0 

00:00:06.34 

2886 

63 


Using the <syntax> tag 

The <SYNTAX> tag lets you distinguish the syntax of a programming 
language statement from regular text. The <SYNTAX> tag distinguishes 
the syntax statement by making the typeface of the statement different from 
the typeface used in the surrounding text. The <SYNTAX> tag is terminated 
by the <ENDSYNTAX> tag. 

The <SYNTAX> tag accepts two optional arguments. The WIDE keyword 
argument allows more width for the syntax statement by letting the syntax 
statement extend into the left margin. The alternate-heading argument lets 
you specify a heading for the syntax statement. 

The following example shows how you can use the <SYNTAX> tag to 
separate a S5mtax statement from the surrounding text. Note that all the 
spacing in the statement is retained as it was entered. 

<SYNTAX> 

IF condition THEN 
statement-list 
[ELSE 

statement-list]; 

<ENDSYNTAX> 

This example may produce the following output; 

IF condition THEN 
statement-list 

[ELSE 

statement-list]; 
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Using the <argument> tag 

The < ARGUMENT > tag lets you label an argument by displaying that 
argument in a typeface that differs from that of the surrounding text (for 
example, in some doctypes it may cause the argument to be displayed in a 
bold typeface). This tag accepts only the argument name as an argument. 

The following example shows how you can use the <ARGUMENT> tag to 
separate the argument from the surrounding text. 

The CHR$ function converts the <ARGUMENT>(char-data) argument 
into a numeric value. 

' This example may produce the following output. 

The CHR$ function converts the char-data argument into a 
numeric value. 


8.1.3 Documenting Software Messages 

You can describe the messages put out by software programs by using the 
<MESSAGE_SECTiON> tag and the tags it enables. The tags made available 
by the <message_section> tag allow you to label messages issued by an 
operating system or an application program, and to enter descriptions of those 
messages. 

The tags enabled by the <messsage_section> tag are summarized in the 
following list. 

<MESSAGE_TYPE> Specifies the type of message being described using the 
<MSG> or <MSGS> tag. 

<MSG> Labels and formats up to two lines of message text within 

the message description section. 

<MSGS> Labels and formats up to nine lines of message text within 

the message description section. 

<MSG_TEXT> Specifies the explanatory text associated with the 

messages described by the <MSG> or the <MSGS> 
tag. 

Messages generally come in one of three forms: 

• A message text string only. An example of this type of string is "System 
Resources Unavailable." 

• A message text string preceded by a text string identification code. An 
example of this type of string is "%DIRECT-W-NOFILES, no files found." 

• A message text string preceded by a numeric string identification code. 
An example of this type of string is "%1288374 file lookup failed." 

The < MESSAGE _SECTiON> tag begins the message description section. This 
tag is terminated by the <endmessage_SECTION> tag. Select the tags you 
need to use in the message description section based upon the following 
criteria: 

• The format your messages most closely follows 

• The number of lines each message occupies on the terminal display 
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Using the <message_type> tag 

Use the < MESSAGE-TYPE > tag to specify the type of message labeled by 
the <MSG> or <MSGS> tags. The < MESSAGE-TYPE > tag accepts one of 
three keywords as the argument that determines the type of messages being 
described: 

• NOIDENT 

Specifies that the <MSG> and <MSGS> tags in the message section will 
not be passed a numeric or text identification string as the first argument. 
NOIDENT is the default keyword. Specifying NOIDENT as the keyword 
argument has the same effect as not specifying the <MESSAGE-TYPE> tag 
at all. 

• TEXTIDENT 

Specifies that the <MSG> and <MSGS> tags in the message section will 
be passed a text identification string as an argument. 

Text identification strings and message text arguments should be specified 
as pairs. The TEXTIDENT keyword creates a comma (,) between text 
identification strings and message text arguments. 

• NUMIDENT 

Specifies that the <MSG> and <MSGS> tags in the message section will 
be passed a numeric identification string as an argument. 

Numeric identification strings and message text arguments should be 
specified as pairs. The NUMIDENT keyword assumes that the numeric 
identification string specified will not exceed a total length of six picas 
(approximately ten characters). 

The following is a sample use of the <messagE-TYPE> tag. Note how 
the NUMIDENT keyword indicates that the message being described has a 
numeric identification code. 

<MESSAGE_SECTION> 

<MESSAGE_TYPE>(NUMIDENT) 

<MSG>C/.1288374\file lookup failed.) 


Using the <msg> tag 

The <MSG> tag is used for messages that occupy only one or two lines when 
they are output. The arguments accepted by the <MSG> tag are based upon 
the t 5 ^e of message being described. The message type is determined by the 
keyword argument used with the <messagE-TYPE> tag. 

• NOIDENT keyword 

The <MSG> tag requires a message text argument and accepts an 
optional second message text argument. 
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• TEXTIDENT keyword 

The <MSG> tag requires a text message identification string and a 
message text argument. It also accepts a second line of message text as 
an optional third argument. The TEXTIDENT keyword creates a comma 
(,) between text identification strings and message text arguments. The 
optional second message text argument is stacked under the first message 
text. 

• NUMIDENT keyword 

The <MSG> tag requires a numeric message identification string and a 
message text argument. It also accepts a second line of message text as 
an optional third argument. The numeric message identification string 
must be no longer than ten characters (six picas) in length. The optional 
second message text argument is stacked under the first message text. 

The following is a sample use of the <MSG> tag. Note how the optional 
third argument is used for the additional message text. 

<MESSAGE_SECTION> 

<MESSAGE_TYPE>(NUMIDENT) 

<MSG>('/ol244374\file lookup failedXdirectory not found) 


Using the <msgs> tag 

The <MSGS> tag is used for messages that occupy from one or nine lines 
when they are output. The arguments accepted by the <MSGS> tag are 
based upon the type of message being described. The message type is 
determined by the keyword argument used with the < MESSAGE—TYPE > tag. 

• NOIDENT keyword 

The <MSGS> tag requires one message text argument and accepts up to 
a total of nine message text arguments. 

• TEXTIDENT keyword 

The <MSGS> tag requires text message identification strings as the first 
and optionally as the third, fifth, and seventh arguments. It also requires 
a message text argument as the second argument and optionally as the 
fourth, sixth and eighth arguments. The TEXTIDENT keyword creates a 
comma (,) between text identification strings and message text arguments. 
The optional arguments are stacked under the required arguments. 

• NUMIDENT keyword 

The <MSGS> tag requires numeric message identification strings as the 
first and optionally as the third, fifth, and seventh arguments. It also 
requires a message text argument as the second argument and optionally 
as the fourth, sixth and eighth arguments. The text message identification 
strings must be no more than 10 characters (approximately six picas 
in length). The optional arguments are stacked under the required 
arguments. 

The following is a sample use of the <MSGS> tag. Note how the numeric 
identification codes and the text strings associated with them are specified in 
pairs. 
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<MESSAGE_SECTION> 

<MESSAGE_TYPE>(NUMIDENT) 

<MSGS>(*/,133455\read write error\*/i0000221\disk not available 
\$6644544\file not found) 


Using the <msg_text> tag 

The <MSG_TEXT> tag labels the text that describes the messages listed by 
the <MSG> or <MSGS> tags. By default the <MSG_TEXT> tag has a 
heading of "Explanation:." If you want the heading for your text to be more 
descriptive, you can specify an alternate heading for this tag (for example, 
"User Action"). Note that any alternate heading specified for the <MSG_ 
TEXT> tag will have a colon (:) appended to the end of the heading when it 
is output. 

The following example shows how you can use the tags enabled by the 
<MESSAGE_SECTiON> tag to create a message description section. Note how 
using the <MESSAGE_TYPE> tag with the TEXTIDENT keyword results in a 
comma (,) being placed after each message identification string. 

<MESSAGE_SECTION> 

<MESSAGE_TYPE>(TEXTIDENT) 

<MSG>(BACKLINK\Incorrect directory back link) 

<MSG_TEXT>(Facility) VERIFY. Verify Utility 
<MSG_TEXT>(Severity) BACKLINK-F-BADLINK 
<MSG_TEXT> 

The Verify Utility could not process your command, please check the 
syntax of your statement. 

<MSGS>(UAF-E-NAOFIL\Unable to open file SYSUAF.DAT\-RMS-E-FNF\file not found) 
<MSG_TEXT>(User Action) 

Check the syntax and reenter the command. 

<MSG_TEXT> 

This is some explanatory text for the previous message. 

<ENDMESSAGE_SECTION> 

This example may produce the following output. 

BACKLINK, Incorrect directory back link 
Facility; VERIFY, Verify Utility 
Severity: BACKLINK-F-BADLINK 

Explanation: The Verify Utility could not process your command, please 
check the syntax of your statement. 

UAF-E-NAOFIL, Unable to open file SYSUAF.DAT 
-RMS-E-FNF, file not found 

User Action: Check the syntax and reenter the command. 

Explanation: This is some explanatory text for the previous message. 
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8.1.4 


Documenting Arguments, Parameters and Qualifiers 


There are four sets of tags available in the SOFTWARE doctype for describing 
arguments, parameters, and qualifiers in a list. 


<ARGDEFLIST> 

<PARAMDEFLIST> 

<QUALDEFLIST> 

<QUAL_LIST> 


Creates a definition list of arguments 
Creates a definition list of parameters 
Creates a definition list of qualifiers 
Creates a summary list of qualifiers 


The tags used to create these SOFTWARE doctype definition lists and the 
form of these lists are very similar to those used by the global <DEFINITI0N_ 
LIST> tag. The qualifier summary list differs from the definition lists in that it 
is designed only as a summary list of qualifiers and contains no provision for 
definition text. 

These SOFTWARE doctype-specific tags are used to label lists of arguments, 
parameters or qualifiers inside or outside the context of the reference 
templates. 


Using the SOFTWARE Definition List Tags 

The following list describes the software definition list tag sets. Note that tags 
that function in the same manner in each of the definition lists are described 
together. 


Software Definition List Tags 

<ARGDEFLIST> 

<PARAMDEFLIST> 

<QUALDEFLIST> 

Begins each type of list and enables the following tags. Each of these tags 
allows an optional heading to be specified as an argument. The NONE 
keyword argument may also be used to indicate that the list contains no 
items. 

If these tags are used inside of a reference template, default headings may be 
defined. 


<ARGITEM> 

<PARAMITEM> 

<QUALITEI\/I> 

Labels the argument, parameter or qualifier to be listed. Each of these tags 
requires one argument and accepts up to a total of seven arguments to list 
any related arguments, parameters, or qualifiers. 

<ARGDEF> 

<PARAMDEF> 

<QUALDEF> 

Labels the text string that describes the appropriate argument, parameter or 
qualifier. 

<ENDARGDEFLIST> 

< ENDP AR AMDEFLIST> 

<ENDQUALDEFLIST> 

Terminates each type of list and disables the contained tags. 
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The following examples show how to create an argument definition list, a 
parameter definition list, and a qualifier definition list. 

The first example shows a parameter definition list within the Command 
template. This coding of the <PARAMDEFLIST> tag uses the NOHEAD 
keyword to suppress the output of a default heading (in this case, the heading 
"parameters)." If this definition list were coded outside of the context of a 
reference template, no default heading would be defined and the NOHEAD 
argument would not be needed. 

<P>The system maintains logical names and their 
associated equivalence strings in two types of tables: 

<PARAMDEFLIST>(NOHEAD) 

<PARAMITEM>(process-private) 

<PARAMDEF>These tables contain logical names that are available only 
to your process. 

<PARAMITEM>(shareable) 

<PARAMDEF>These tables contain logical names that are available to other 
processes on the system. 

<ENDPARAMDEFLIST> 

This example may produce the following output: 

The system maintains logical names and their associated equivalence strings 
in two types of tables: 

process-private 

These tables contain logical names that are available only to your process. 

shareable 

These tables contain logical names that are available to other processes on the 
system. 

The following example shows how to use the < align-AFTER > tag for 
additional formatting flexibility in an argument definition list outside of a 
reference template. 

<ARGDEFLIST> 

<ARGITEM>(STATUS:arg\ 

<ALIGN_AFTER>(STATUS:)C0MMAND\ 

<ALIGN_AFTER>(STATUS:)TASK) 

<ARGDEF>Specifies whether exit status is to be returned 
from the RUN command. 

<ENDARGDEFLIST> 

This example may produce the following output: 

STATUSiarg 

COMMAND 

TASK 

Specifies whether exit status is to be returned from the RUN command. 


8-15 



Using the SOFTWARE Doctype 


The following example shows a qualifier definition list within the Command 
template. Note how the related qualifiers are stacked. 

<CaMMAND_SECTION> 

<qUALDEFLIST>(Qualifiers) 

<QUALITEM>(/HERE\/THERE) 

<QUALDEF> 

The /HERE qualifer specifies the location of your workplace; 
the /THERE qualifier specifies the location of your home; 

/THERE is the default. 

<QUALITEM>(/TIME\/NOTIME) 

<QUALDEF> 

Specifies the amount of free time you have available. 

If the /TIME qualifier is used, an amount must be given; 

/NOTIME is the default. 

<ENDQUALDEFLIST> 

<ENDCOMMAND_SECTION> 

This example may produce the following output: 

Qualifiers 

/HERE 

/THERE 

The /HERE qualifier specifies the location of your workplace; the /THERE 
qualifier specifies the location of your home; /THERE is the default. 

/TIME 

/NOTIME 

Specifies the amount of free time you have available. If the /TIME qualifier 
is used, an amount must be given; /NOTIME is the default. 

Using the Software Qualifier Summary List Tags 

VAX DOCUMENT provides several tags to create a summary list of command 
qualifiers. The list generated by these tags creates two default headings, and 
places one heading over each qualifier listed by the <QPAIR> tag. Although 
qualifier summary lists are most often used following the <FORMAT> tag 
in the Command template, they may be used either inside or outside of the 
context of the reference templates. 
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Use the following tags to create a qualifier summary list: 

• <QUAL_LIST> 

Begins the list and enables the <QUAL_LIST_HEADS> , <QUAL_LIST_ 
DEFAULT-HEADS> , <QPAIR> , and <ENDQUAL_LIST> tags. This tag 
places two default headings on the page. The heading "Command 
Qualifiers" is placed over the first list column and the heading "Defaults" 
is placed over the second list column. These headings may be overridden 
by the <qual_list_heads> or <qual_list_default_heads> tags. 

The NONE keyword argument can be used to indicate that there are 
no qualifiers. If the NONE keyword is used, the <ENDQUAL_LIST> tag 
should not be used. This tag is terminated by the <ENDQUAL_LIST> tag. 

• <QUAL_LIST_HEADS> 

Creates alternate headings for a single qualifier summary list. This tag 
requires two arguments, which specify the alternate headings. If either 
argument is null, the associated heading is not output. 

• <QUAL-LIST-DEFAULT-HEADS > 

Creates new default headings for all subsequent qualifier summary lists. 
This tag requires two arguments, which specify the new default headings. 
If either argument is null, the associated heading is not output. 

• <QPAIR> 

Specifies the pair of qualifiers to be listed. This tag requires two qualifier 
arguments; the first argument is listed under the default heading 
"Command Qualifiers," the second argument is listed under the default 
heading "Defaults." 

The following example shows a qualifier summary list. Note how no 
description text is used. Note also how each list has a default heading. 

<QUAL_LIST> 

<QPAIR>(/HEREX/THERE) 

<QPAIR>(/TIMEX/NOTIME) 

<ENDQUAL_LIST> 

This example may produce the following output. 


Command Qualifiers 

/HERE 

/TIME 


Defaults 

/THERE 

/NOTIME 
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8.1.5 Creating A Series of Interactive or Code Examples 

Often, it is useful to explain concepts through the use of examples. You 
can create a series of numbered interactive and code examples by using the 
<EXAMPLE_SEQUENCE> tag. 

Interactive and code examples within an example sequence have the 
same form and accept the same tags as examples created using the global 
<INTERACTIVE> and <CODE_EXAMPLE> tags. 

You can use the following tags to construct a sequence of examples: 

• <EXAMPLE_SEQUENCE> tag 

Begins a sequence of numbered informal examples. This tag accepts two 
optional arguments, which are used to alter the heading and suppress the 
numbering of examples. 

The heading-info argument alters the example sequence heading. This 
argument can be one of the following; 

— An alternate heading for the example sequence 

— The NOHEAD keyword, which suppresses the output of a heading 
for the example sequence 

— The EXAMPLE keyword, which suppresses numbering of the 
examples in the sequence and outputs the heading "Example"; this 
keyword should be used when you have a single informal example 
rather than a series of examples. 

The NONUMBER keyword argument suppresses the numbering of 
examples in an example sequence. When the keyword EXAMPLE is used 
as the heading-info argument, the NONUMBER keyword argument is 
unnecessary. 

The <EXAMPLE_SEQUENCE> tag enables the <examples_intro> , 

<EXC> , <EXI> , and <extext> tags. This tag is terminated by the 
<ENDEXAMPLE_SEQUENCE> tag. 

• <EXAMPLES_INTRO> 

Specifies introductory text for the example sequence. 

• <EXC> 

Specifies the beginning of a code example within an example sequence. 
This code example is formatted exactly the same as those created using 
the global <code_example> tag. The code example is terminated by 
the <EXTEXT> tag. 

• <EXI> 

Specifies the beginning of an interactive example within an example 
sequence. This tag uses the global <S> and <U> tags within the 
example in the same manner as the global <interactive> tag. The 
interactive example is terminated by the <extext> tag. 

• <EXTEXT> 

Specifies text that explains the previous example in the sequence. This tag 
is required to terminate examples begun using the <EXC> and <EXI> 
tags. 
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The following example shows how the example sequence tags can be used. 
Note the alternate heading specified as an argument to the <EXAMPLE_ 
SEQUENCE > tag. 

<EXAMPLE_SEQUENCE>(An Interactive Example and a Code Example) 

<EXAMPLES_INTRO> 

This is introductory text for the sample examples. 

<exi><S>($ )<U>(SET WORK/NOTIME) 

<EXTEXT> 

This command sets the /NOTIME qualifier to the SET WORK command. 

<EXC> 

This is a code example, ined, exactly as entered, 

note how f a 

0 t 

r e 

matting is r 

<EXTEXT> 

This shows the flexibility available within a code example in an example 
sequence. 

<ENDEXAMPLE_SEqUENCE> 

This example may produce the following output: 

An Interactive Example and a Code Example 

This is introductory text for the sample examples. 

Q $ SET WORK/NOTIME 

This command sets the /NOTIME qualifier to the SET WORK command. 

0 

■■ This is a code example, ined, exactly as entered. 

note how f a 

0 t 

re 
matting is r 

This shows the flexibility available within a code example in an example 
sequence. 


Using the Reference Templates 

The SOFTWARE doctype contains four tag templates that let you create 
software reference documentation. A tag template is a set of tags that are 
intended for some specialized documentation purpose, such as creating an 
outline, composing the front matter of a book, or documenting a series of 
software commands. 

Every tag template has a beginning and an end. These template boundaries 
are set by a pair of tags: 

• The template-enabling tag begins the template and sets up all the template- 
specific formats and tag definitions. 

• The template-ending tag ends the template and disables the template- 
specific formats and definitions. 

If template-specific tags are encountered outside of the template in which 
they are defined, these tags will be undefined and VAX DOCUMENT will 
issue a warning message. Note that you must end a template before you 
begin another template; templates cannot be nested inside one another. 
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Tag templates are especially useful in creating and maintaining reference 
documentation. They make the coding of reference information easier in 
several ways: 

• The structured nature of tag templates makes it easier to consistently 
code, format, and order reference information. 

• Text coded into a tag template is more modular and structured than the 
text in a nontemplated SDML file, which makes it easier to modify and 
maintain reference information. 

• Using a tag template for reference information allows the writer to "fill 
in the blanks," and helps ensure that no essential information, such as 
restrictions or the lack of restrictions on a command, is omitted. 

• Using a tag template for reference information lets you use default 
formats, headings, and tags. This helps guarantee that even when several 
writers work on different portions of the same book, all of these portions 
look alike. 

For these reasons, VAX DOCUMENT provides the reference templates that are 
tag templates specialized for the description of software reference information. 

Using the SOFTWARE Doctype Reference Templates 

There are four reference templates available in the SOFTWARE doctype to 
create reference documentation for software commands, routines, statements, 
or VAX DOCUMENT tags: 

• Cornmand template 

Describes commands and their various components. Examples of 
command descriptions are the descriptions of the DCL commands used in 
the VMS operating system. 

• Routine template 

Describes software routines and their various components. Examples of 
routines descriptions are the descriptions of the VMS run-time library 
routines. 

• Statement template 

Describes programming language constructs (such as statements and 
functions) and their various components. An example of a statement 
description is the CASE statement available in the VAX Pascal 
programming language. 

• Tag template 

Describes VAX DOCUMENT tags and their components. Examples of tag 
descriptions can be found in the reference chapters in this manual. 

These templates are similar in design because all are intended to be used 
to create similarly formatted reference material. This similarity means 
that certain tags are common to all four templates; however, because each 
template is customized for the presentation of a particular kind of information, 
several tags are available only in specific templates. For example, all four 
templates have a description section that describes the current command, 
routine, statement, or tag. However, only the Routine template has a section 
for describing in detail the values returned by a routine. 
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Like all tag templates, the software reference templates are begun by a 
template-enabling tag (for example, the <COMMAND_SECTlON> tag), and 
terminated by a similarly-named template-ending tag (for example, the 
<ENDCOMMAND_SECTlON> tag). However, because the reference templates 
are designed to create reference-oriented documentation, they also must 
contain one or more reference-element tags. 

A reference-element is a single element in a reference section; for example, 
the description of a single command in a command reference section, or 
the description of a single routine in a routine reference section. It is the 
collection of these single elements into a group that creates a reference 
section. 

The default reference-element tag names match the templates they are used 
in. The < COMMAND > tag occurs in the Command template, the < ROUTINE > 
tag occurs in the Routine template, and so on. When these reference- 
element tags occur in a reference template, they signal the beginning of a 
new reference-element description. 

By default, each new reference-element description begins on a new output 
page, with the name of the current reference-element output at the top of the 
page. 

Reference-element tags are not terminated by matching ending tags as are 
most template tags. Instead, a reference-element description is terminated 
either by the next reference-element tag, by the end of the reference template, 
or by the end of the SDML file. 

Note that of all the tags used in the various reference templates, only the 
template-enabling tags and the reference-element tags are required; all other 
tags used in the templates are optional. 

The following list shows the template-enabling tag and the reference-element 
tag for each template. 


Template 

Name 

Template-Enabling 

Tag 

Reference- Element 

Tag 

Command 

<COMMAND_SECTION> 

<COMMAND> 

Routine 

<ROUTINE_SECTION> 

<ROUTINE> 

Statement 

< ST ATEMENT-SECTION > 

r <STATEMENT> ^ | 

1 < FUNCTION > / 

Tag 

<TAG_SECTION> 

<SDML_TAG> 

^The use of braces indicates that the enclosed tag names are used 
interchangeably, VAX DOCUMENT provides two such names to improve the 
readability of your SDML file. 


The Default Format of the Reference Templates 

The software reference templates all have the same default output format. 
When a reference template is begun by specifying a template-enabling tag, 
the template has the following format: 

• A new reference-element description is begun and placed at the beginning 
of a new output page. 
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For example, each time a < command > tag is encountered in the 
command template, a new reference-element description is begun and 
placed at the beginning of the next output page. 

• The name of the current reference-element is placed on each output 
page. The placement of this name depends on the doctype used. In most 
doctypes, this name is placed at the top of the page. 

For example, if a command called SET TIME was being described 
and had been specified as < command > (SET TIME) in the 
SOFTWARE.REFERENCE doctype, then the single line running heading 
"SET TIME" would be placed at the top of the output page above the 
reference description. 

• Each page is numbered using the last major page number prefix. 

For example, if Chapter 2 was the immediately preceding chapter, then 
"2" would be the prefix associated with the page numbers in the reference 
section; likewise "A" would be the prefix if appendix A had preceded the 
reference section. 

• Default headings are defined by the reference template for those tags that 
have such headings. 

For example, the <RESTRICTI0NS> tag has associated with it the default 
heading text "Restrictions" in the templates in which it is available. 

Using the NONE Keyword Argument to Template Tags 

Most of the reference template tags place a heading on the output page. 

All of these tags accept the keyword NONE as an argument. This keyword 
indicates that the heading should be placed on the output page followed by 
the text "None." 

By using the NONE keyword, you ensure that a particular kind of information 
is explicitly declared as nonexistent or not applicable in a reference-element 
description. Use the NONE keyword rather than typing the word "None." 
under the heading because inconsistencies in formatting and spelling of the 
word may otherwise be introduced. 

When you use the NONE keyword as an argument to a template tag, the tag 
that terminates that template tag must be omitted. For example, if you specify 
the NONE argument to the <paramdeflist> tag, the <endparamdeflist> 
tag must be omitted. 

Of all the tags that output a heading in the reference templates, only the 
<FORMAT> , <STATEMENT_FORMAT> , and <DESCRIPT10N> tags do not 
accept a keyword argument of NONE, because placing the text "None," 
beneath the headings output by any of these tags would be inappropriate. If 
there is no format or description sections, these tags should be omitted. 

Using Samples of the Reference Templates 

VAX DOCUMENT provides the following sample reference template SDML 
files in the directory DOC$TEMPLATES: 


8-22 



Using the SOFTWARE Doctype 


Command Template: 
Routine Template: 
Statement Template: 
Tag Template: 


DOC$TEMPLATES:COMMAND.SDML 

DOC$TEMPLATES:ROUTINE.SDML 

DOC$TEMPLATES:STATEMENT.SDML 

DOC$TEMPLATES:TAG.SDML 


You can also enter an editing session with LSE and expand the appropriate 
template tags into a reference template SDML file. See the VAX DOCUMENT 
User Manual, Volume 1 for more information on using LSE with 
VAX DOCUMENT. 

See the template samples at the end of this chapter for examples of the SDML 
code and output from each of the four reference templates. 


8.2.1 Documenting Reference-Elements within Templates 

When describing a reference-element (such as a command or function) in a 
template, it is often useful to provide both a brief description and a detailed 
explanation of the reference-element. The tags used for this purpose are the 
<OVERVIEW> and <DESCRIPTION> tags. 

• <OVERVIEW> 

Used to briefly describe the reference-element. Such overviews are 
typically a single-sentence summary of the reference-element. 

• <DESCRIPTION> 

Used to describe the reference-element in detail. This description may 
cover suggested use, special considerations, or how to use the reference- 
element with related commands, routines, statements, or tags. Such 
description sections can be as short as two or three sentences or may be 
as long as several pages. 

Chapter 14 contains more detailed reference material on each of these tags. 

The following SDML code fragment shows a sample use of the <OVERVlEW> 
and <DESCRlPTiON> tags within the context of the Command template. The 
<C0MMAND> tag and the global <format> and <paramdeflist> tags are 
included to make a more complete example. Note how the inclusion of the 
reference-element tag ( < command > ) forces a page break by default. 

<COMMAND_SECTION> 

<COMMAND>(SET TIME) 

<0VERVIEW> 

Resets the system time to the time specified as a parameter to this commcmd. 
<ENDGVERVIEW> 

<F0RMAT> 

<FCMD>(SET TIME) <FPARMS>(time-specification) 

<ENDFORMAT> 

<PARAMDEFLIST> 

<PARAMITEM>(time-specification) 

<PARAMDEF> Specifies the time to which the system should he set. 

<ENDPARAMDEFLIST> 

<DESeRIPTION> 

The SET TIME command lets you reset the system clock on your VMS system. 

This command is generally used to make allowances for daylight savings time 
and other such events. 

<ENDDESCRIPTION> 

<ENDCOMMAND_SECTION> 

This example may produce the following output: 
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SET TIME 

Resets the system time to the time specified as a parameter to this 
command. 

FORMAT 

SET TIME time-specification 

PARAMETERS 

time-specification 

Specifies the time to which the system should be set. 

DESCRIPTION 

The SET TIME command lets you reset the system clock on your VMS 
system. This command is generally used to make allowances for daylight 
savings time and other such events. 
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8.3 Creating Your Own Reference Template Tags 

VAX DOCUMENT provides the following tags for the creation of specialized 
reference template tags: 

• <SET_TEMPLATE_LIST> 

Creates a user-defined set of tags for creating your own headed list within 
the template. 

• <SET_TEMPLATE_PARA> 

Creates a user-defined set of tags for creating your own headed template 
paragraph section within the template. 

• < SET-TEMPLATE-TABLE > 

Creates a user-defined set of tags for creating your own headed table 
within the template. 

Each of these tags defines a template tag and its terminator for use within a 
template section. You can specify the following arguments to these tags: 

• Name by which a template tag is to be invoked 

• Default heading for the tag when it is invoked 

• Name of tags defined within the context of the template tag 

For example, if you specify "MYLIST" as the first argument to the <SET_ 
TEMPLATE-LIST> tag, you would define a list that is begun by the <MYLIST> 
tag and terminated by the <endmylist> tag. If you specify "My List" as 
the second argument to the <SET-TEMPLATE_list> tag, you would define a 
default heading for this list of "My List." And if you specify "MY_ITEM" as 
the third argument to the <SET-TEMPLATE_list> tag, you would define the 
tag <MY_ITEM> as a tag to be used within the context of the <MYLIST> tag. 

Each of the tags defined using these tags accepts an alternate heading 
argument and the NONE keyword argument. Note that these user-defined 
template tags have the same behavior as standard template tags. If the NONE 
keyword argument is specified, the terminating tag must not be used. 


8.3.1 Creating Your Own Template Lists 

The <SET_TEMPLATE_LIST> tag lets you create your own user-defined set of 
tags for listing information. This tag requires four arguments and accepts an 
optional fifth argument. This tag has the following syntax. 

<SET_TEMPLATE_LIST> {list-tag-name 

\ default-list-heading 
\ list-item-tag-name 
\list-type 
[\heading-level]} 
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The following list summarizes the arguments allowed by this tag in the order 
in which they must be specified: 

list-tag-name 

Specifies the name of the tag that will begin the user-defined list. This name 
is also used for the terminating tag name. For example, if the list-tag-name 
argument is specified as "SAMPLE—LISTTAG," the beginning tag will be 
<SAMPLE_LISTTAG> and the terminating tag will be < ENDS ample _listtag> . 

The user-defined tag created by this argument is similar to the global <LIST> 
tag. 

default-list-heading 

Specifies the default text heading to be output by the user-defined list. This 
heading can be overridden by an alternate heading specified as an argument 
to the <list-tag-name> tag. 

list-item-tag-name 

Specifies the name of the tag to be used to indicate individual items in the list 
being defined. For example, if the list-item-tag-name argument is specified as 
"SAMP—ITEM," the individual list item tag will be <SAMP_ITEM> . 

The user-defined tag created by this argument is similar to the global <LE> 
tag. 

list-type 

Specifies the keyword that indicates the type of list on which the user-defined 
list is based. There are three available keywords: 

SIMPLE 

NUMBERED 

UNNUMBERED 

These keywords have the same effect as the keywords of the same name used 
with the global <LIST> tag. 

heading-level 

Specifies the heading level to be associated with the tag. The accepted 
arguments are as follows: 

• 1 — Specifies a primary template heading level 

• 2 — Specifies a secondary template heading level 

If this argument is not specified, the value defaults to 2. 

Note that the case of the text output by the template heading is controlled by 
the doctype under which the SDML file is processed. 

The first line of the first example shows how the user-defined < SHOPPING- 
LIST> tag is defined using the < SET-TEMPLATE-LIST > tag. The following 
examples show various uses of the <SH0PPING-LIST> tag. 

The first example shows the < SHOPPING-LIST > tag defined with a heading 
value of 1 and the second example shows the same tag defined with the 
default heading value of 2. Note how this change affects the printed output. 
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<COMMAND_SECTION> 

<SET_TEMPLATE_LIST>(SHOPPING_LIST\Shopping List\SHOP_ITEM\NUMBERED\l) 
<SHOPPING_LIST> 

<SHOP_ITEM>Hair gel 
<SHOP_ITEM>Beer nuts 
<SHOP_ITEM>Frisbee 
<ENDSHOPPING_LIST> 

This example may produce the following output: 

SHOPPING 1 Hair gel 

LIST 2 Beer nuts 

3 Frisbee 

The following example shows how an alternate heading may be specified for 
a user-defined list. It also shows how the NONE keyword argument may be 
specified. Note that both of these arguments are optional. 

<COMMAND_SECTION> 


<SET_TEMPLATE_LIST>(SHOPPING_LIST\Shopping List\SHOP_ITEM\NUMBERED) 
<SHOPPING_LIST>(NONE) 

<SHOPPING_LIST>(Bobs Wood Goods) 

<SHOP_ITEM>Wooden Tables 
<SHOP_ITEM>Wooden chairs 
<ENDSHOPPING_LIST> 

<SHOPPING_LIST>(Bloomingdales\NONE) 

This example may produce the following output: 

shopping list None. 

bobs wood goods 1 Wooden Tables 

2 Wooden chairs 


bloomingdales None. 


8.3.2 Creating Your Own Template Sections 

The < SET-TEMPLATE-PARA > tag lets you create your own user-defined set 
of tags for making a template section. This tag requires two arguments and 
accepts an optional third argument. This tag has the following syntax. 

<SET_TEMPLATE_PARA> {para-tag-name 

\ default-para-heading 
[\heading-level]} 

The following list summarizes the arguments allowed by this tag in the order 
in which they must be specified: 
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para-tag-name 

Specifies the name of the tag that will begin the user-defined paragraph 
section. This name is also used for the terminating tag name. For example, 
if the para-tag-name argument is specified as "SAMPLE _PARATAG," the 
beginning tag will be < SAMPLE _PARATAG> and the terminating tag will be 
<ENDSAMPLE_PARATAG> . 

default-para-heading 

Specifies the default text heading to be output by the user-defined paragraph 
section. This heading can be overridden by an alternate heading specified as 
an argument to the < para-tag-name > tag. 

heading-level 

Specifies the template heading level to be associated with the tag. The 
accepted arguments are as follows: 

• 1 — Specifies a primary template heading level. 

• 2 — Specifies a secondary template heading level. 

If this argument is not specified, the value defaults to 2, and the secondary 
template heading is used. 

Note that the case of the text output by the template heading is controlled 
by the doctype. For example, in some doctypes specifying the value 1 might 
result in the heading being output in all uppercase text, and specifying the 
value 2 might result in the heading being output in all lowercase text. 

The following examples show how to create a template tag called <SIDE_ 
EFFECTS> using the <set_template_para> tag. The first example uses 
the <SET_TEMPLATE_PARA> tag to define the tag < SIDE-EFFECTS > as the 
beginning tag of a paragraph template that has a default heading of "Side 
Effects:." Note that this first definition uses the a heading level value of 1 
for the < SIDE-EFFECTS > tag. Note how the second <SIDE-EFFECTS> tag 
example explicitly specifies a default heading level value of 2. 

<COMMAND_SECTION> 

<SET_TEMPLATE_PARA>(SIDE_EFFECTS\Side Effects:\1) 

<SIDE_EFFECTS> 

Modifying the arguments to the PLACE command changes the positioning of the 
page number. 

<ENDSIDE_EFFECTS> 

This example may produce the following output: 


SIDE 

EFFECTS: 


Modifying the arguments to the PLACE command changes the positioning of 
the page number. 

The following example illustrates how to specify the template tag <SIDE- 
EFFECTS> with an alternate heading of "desired effect=," and shows how the 
NONE keyword argument can be used. 

Note how the alternate heading "desired effect=" overrides the default 
heading specified by the <SET_templatE-PARA> tag for the current tag. 
Note also how this definition of the < SIDE-EFFECTS > tag has a heading level 
of 2, Note how the second <sidE-EFFECTS> tag uses the default heading. 
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<COMMAND_SECTION> 


<SET_TEMPLATE_PARA>(SIDE_EFFECTS\side effects:\2) 

<side_effects>(desired effect=) 

Modifying the arguments to the PLACE command changes the positioning of the 
page number. 

<endside_effects> 

<side_effects>(NONE) 

<ENDCOMMAND_SECTION> 

This example may produce the following output: 


desired effect= Modifying the arguments to the PLACE command changes the positioning of 

the page number. 


side effects: None. 


8.3.3 Creating Your Own Template Tables 

The < SET-TEMPLATE-TABLE > tag lets you create your own user-defined set 
of tags for making a table with optional headings within a template. Tables 
created using this tag can have either two or three columns. This tag requires 
five arguments and accepts the optional tahle-column-headings argument. This 
tag has the following syntax: 

<SET_TEMPLATE_TABLE> {table-tag-name 

\ default-table-heading 
\ table-row-tag-name 
\column-count 
\column-widths 
[\ table-column-headings]} 

The following list summarizes the arguments allowed by this tag in the order 
in which they must be specified: 

table-tag-name 

Specifies the user-defined name of the tag that begins the user-defined table. 

default-table-heading 

Specifies the default text heading to be output over the entire user-defined 
table. This heading can be overridden by an alternate heading specified as an 
argument to the < table-tag-name > tag. 

table-row-tag-name 

Specifies the name of the tag to be used to indicate individual table rows 
in the table being defined. For example, if the table-row-tag-name argument 
is specified as "SAMP_ROW," the individual table row tag will be <SAMP- 
ROW> . 

The user-defined tag created by this argument is similar to the global 
< TABLE-ROW > tag. 
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column-count 

Specifies the number of columns in the user-defined table. The accepted 
arguments are as follows: 

• 2 — Specifies that the table is to have two columns. 

• 3 — Specifies that the table is to have three columns. 

table-column-widths 

Specifies the approximate widths of the table columns. The width of the 
last table column is determined by VAX DOCUMENT. So, if you specify a 
two-column list, you must specify only one column-width argument as shown 
in the following code example. 

<SET_TEMPLATE_TABLE>(KEYVALS\Keyword Values\KEYVAL\2\10\Keyword\Value) 

If you specify a three-column list, you must specify two column-width 
arguments as shown in the following code example. 

<SET_TEMPLATE_TABLE>(KEYVAL_LIST\Keyword Ranges\KEYVAL\3\10\10\Keyword\High\Lower) 

table-column-headings 

Specifies optional default headings for each column in the user-defined 
table. If you specified a two-column list, you may specify up to two heading 
arguments. If you specified a three-column list, you may specify up to three 
heading arguments. 

The following examples show a definition of the user-defined 
<RECORDTABLE> table tags. In this example, the <recordtable> tag is 
defined as a two-column list with column headings, and with a default table 
heading of "Best Songs." 

The first use of these table tags in the following example sets the text supplied 
to the two <45RPM> tags in the table, and then terminates the table. The 
second use shows how the NONE keyword argument can be used. 

<SET_TEMPLATE_TABLE>(RECORDTABLE\Best Songs\45RPM\2\12\Performer\Song Title) 
<RECORDTABLE> 

<45RPM>(Sinatra\Strangers in the Night) 

<45RPM>(Moody Blues\Nights in White Satin) 

<ENDRECORDTABLE> 

<RECORDTABLE>(NONE) 

This example may produce the following output: 


best songs 




Performer 

Song Title 


Sinatra 

Strangers in the Night 


Moody Blues 

Nights in White Satin 


best songs None. 
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8.4 Modifying the Reference Templates 

In most cases, you will not find it necessary to modify the reference templates. 
However, if you do wish to modify these formats, you can do so by using one 
of the following tags: 

• <SET_TEMPLATE_HEADING> tag 

Creates new default headings for tags used within the reference 
templates, 

• Template-enabling tags 

Modifies the format of the entire template. This includes creating 
running headings, creating page number prefixes, and setting whether 
the reference template (and any reference-elements within it) begins on a 
new page of output. 

• < SET-TEMPLATE _templatename> tags 

Modifies the format of the reference-element tags used in each template. 
This includes specifying the current reference-element name as a 
secondary running heading, specifying that the reference-element heading 
has additional information stacked beneath it, and specifying whether the 
reference-element tag should begin on a new page of output. 

The modifications made by these tags only affect those tags that follow the 
modifying tag in the SDML file in the current reference template. 


8.4.1 Modifying Default Headings Within a Template 

Each reference template enables several tags that place default headings on 
the output page. In most cases you will not want to change these default 
headings because of the possibility of introducing typographical errors into 
the text of the heading. Changing the default headings can also cause your 
new headings to be incompatible with other headings in the current template 
or with headings in other reference sections. 

However, if you do wish to modify these headings, you can do so by using 
the <SET_TEMPLATE-HEADING > tag, which lets you specify a new default 
heading for a template tag within one of the reference templates. This tag has 
the following syntax: 

<SET_TEMPLATE_H EADING > (element-keyword\ default-heading) 

The <SET_TEMPLATE_HEADING> tag accepts two arguments: the name of 
the template tag to receive the new default heading, and the text of the 
new default heading. The new default heading will then be used by all 
subsequent uses of the template tag named as an argument to the <SET- 
TEMPLATE-HEADING > tag in the current template. This heading overrides 
any previously defined default heading for that template tag in the current 
template. 

A default heading created using the <SET-TEMPLATE-HEADING> tag will be in 
effect until that heading is reset within the current template by another < SET- 
TEMPLATE-HEADING > tag. Note also that the <set-TEMPLATE-HEADING > tag 
has no effect on templates other than the one in which it is used. 
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The following example shows how you would create a new default heading. 
In this example, the default heading for the <RSDEFLIST> tag is set to be 
"Conditions Signalled." 

<ROUTINE_SECTION> 

<SET_TEMPLATE_HEADING>(RSDEFLIST\Conditions Signalled) 

<RSDEFLIST> 

<RSITEM>(SS$_NQRMAL\Service successfully completed.) 

<RSITEM>(SS$_ACCVI0\Acces8 violation.) 

<ENDRSDEFLIST> 

This example may produce the following output: 


CONDITIONS 

SIGNALLED 


SS$_NORI\/IAL 

SS$_ACCVIO 


Service successfully completed. 
Access violation. 


Table 8-1 summarizes the default headings assigned to the standard template 
tags. 

Table 8-1 Default Headings of Reference Template Tags 


Template Tag 

Default Heading 

Command Template Tags 

<FORMAT> 

Format 

<PARAMDEFLIST> 

Parameters 

<QUALDEFLIST> 

Qualifiers 

<DESCRIPTION> 

Description 

<RESTRICTIONS> 

Restrictions 

<PROMPTS> 

Prompts 

Routine Template Tags 

<FORMAT> 

Format 

<ARGDEFLIST> 

Arguments 

<DESCRIPTION> 

Description 

<RSDEFLIST> 

Return Values 

Tag Template 

<FORMAT> 

Format 

<PARAMDEFLIST> 

Arguments 

<RELATED_TAGS> 

Related Tags 

<TERMINATING_TAG> 

Required Terminator 

<DESCRIPTION> 

Description 

Statement Template 

<STATEMENT_FORMAT> 

Format 

<DESCRIPTION> 

Description 
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8.4.2 Using the Template-enabling Tags 

The template-enabling tags are used to begin a reference template, and may 
optionally be used to alter the default format of that template. The following 
table lists the template-enabling tags for each template. 


Template Name 

Template-enabling Tag 

Command Template 

<COMMAND--SECTION> 

Routine Template 

<ROUTINE_SECTION> 

Statement Template 

<STATEMENT_SECTION> 

Tag Template 

<TAG_SECTION> 


All the template-enabling tags have the same syntax and perform the same 
functions. The syntax for the Command template form of the template¬ 
enabling tags is as follows: 

<COMMAND_SECTION>[([running-title][\number-prefix][\NEWPAGE])] 


<ENDCOMMAND_SECTION> 

Arguments to the template-enabling tags are optional. However, if arguments 
are used, they must be specified in the order shown in the previous syntax 
description. 

If you decide to modify a template using the template-enabling tag, these 
modifications will be in effect only within that particular template. The three 
arguments accepted by the template-enabling tags are given in the following 
list. 

running-title 

Sets the second running heading for the page to be the text specified as the 
running-title argument. This argument is valid only when double running 
heads are being used in the template. 

number-prefix 

Sets the numbering prefix to be used to construct page numbers and formal 
figure, table, and example numbers. Such numbers might be DCL-12, STAT- 
5, or Table STAT-3. 

NEWPAGE 

Causes the initial text for the reference section to start on a new page. 

This argument also causes any template reference-element (such as the 
<COMMAND > tag), to begin on a new page. 

When you use a reference template, you typically use it in one of the 
following contexts: 

• In a part begun using the global <PART> tag within a large document. 
Generally, the part follows one or more chapters that are numbered using 
the chapter number as the prefix for page numbers and for formal figure, 
table, and example numbers. 

• In a chapter begun using the global < CHAPTER > tag in a book that has 
chapter-oriented page numbers. 
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• In an appendix begun using the global < APPENDIX > tag that contains 
reference information that is intended to stand alone, that is, can be 
pulled out of the book in which it appears and placed in a binder with 
other system commands or routines. 

In any of these situations you can use multiple reference templates, so long as 
each is terminated before the next reference template begins. 

Note: VAX DOCUMENT does not allow you to nest reference templates inside 
one another and will signal an error if this occurs. 


8.4.3 


Using the <SET_TEMPLATE_templatename> Tags 

The <SET_TEMPLATE_templatename> tag is not a VAX DOCUMENT tag. It is 
a generic name given to a set of four tags that have the same syntax and 
perform the same functions. These tags differ only in their names and in the 
templates in which they are available: 


Command Template 
Routine Template 
Statement Template 
Tag Template 


<SET_TEMPLATE_COMMAND> 

<SET_TEMPLATE_ROUTINE> 

<SET_TEMPLATE_STATEMENT> 

<SET_TEMPLATE_TAG> 


These tags have the following syntax (illustrated by the 
<SET_TEMPLATE_COMMAND> tag in this case): 

<SET_TEMPLATE_COMMAND> (tag-name[\attribute] 

[\attribute][\attribute]) 

These tags let you override the default formatting attributes for reference- 
elements used in each of the reference templates. These tags require a first 
argument that is the name of the reference-element tag in the template. 

You can specify the name of the default reference-element tag (such as the 
< ROUTINE > tag in the Routine template), or you can specify a new tag name 
(such as <MY_ROUTINE> ). 

If you specify a new reference-element tag name, the old tag name is no 
longer valid and should not be used. This new tag name replaces the 
previous reference-element tag. All subsequent uses of a reference-element 
tag should use the last established tag name. 

You can then specify one or more of the following keywords that are accepted 
by these tags (note that these keyword arguments must be separated by 
backslashes): 

NONEWPAGE 

Specifies that reference descriptions are not to start on new pages. By default, 
the tag defined by the first argument of the <SET_TEMPLATE_templatename> 
begins a command description on a new page. 


DOUBLERUNNINGHEADS 

Specifies that the command descriptions have two running titles at the top of 
every page. The top running title will be set by the < COMMAND-SECTION> 
tag or by heading of the most recent <CHAPTER> tag. By default, if a 
doctype design option does not call for running top titles, only the current 
command name is placed at the top of each page. 
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STACK 

Specifies that when multiple arguments are specified for the tag defined by 
the first argument to the <SET_TEMPLATE_templatename> tag, the arguments 
should be stacked at the beginning of the page. 

By default, when multiple arguments are specified, the second and third 
arguments are assumed to be optional descriptive information and are output 
on the same line as the command name. 

The following code example shows a sample use of the <SET_template_ 
COMMAND > tag. In this example, the tag <XYZ_COMMAND> is defined and 
used. The keyword argument NONEWPAGE is specified to the <COMMAND_ 
SECTI0N> tag so that the first description will not start on a new page. The 
keyword argument STACK is specified so that the two arguments "FIND- 
FIRST" and "FF" are stacked with the first argument on top. 

<COMMAND_SECTION>(XYZ Commands\\NEWPAGE) 

<SET_TEMPLATE_COMMAND>(XYZ_COMMAND\NONEWPAGE\STACK) 

<XYZ_COMMAND>(FIND_FIRST\FF) 

This example may produce the following output: 


FIND-FIRST 

FF 


Using the Command Template 

Table 8-2 summarizes the tags available in the Command template, the 
default headings associated with them, and how they should be used. Such a 
table can be found at the beginning of each of the template reference sections. 
Chapter 14 contains the reference information on the tags listed in this table. 

Also included in this section are two subsections, which provide a sample 
use of the Command template. You may find these sample files useful in 
understanding how the Command template tags fit together into a whole. 

• Section 8.5.1 contains an SDML file listing of a sample use of the 
Command template tags. 

• Section 8.5.2 contains a sample output file created using the SDML code 
listed in Section 8.5.1 

These samples describe the APPEND command. These two sections are 
intended only as sample files and should not be used as a source of reference 
for this command. 
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Table 8-2 Tags Available in the Command Template in their Standard Order 


Tag Name 

Default 

Heading 

Template Usage 

<C0MMAND_SECT10N> 

None 

Begins a Command Section 

<SET_TEMPLATE_COMMAND> 

None 

Alters the default format of a Command section 

<SET_TEMPLATE_HEADING> 

None 

Alters the default headings in a reference section 

< SET_TEMPL ATE _P AR A > 

None 

Creates user-defined tags for the creation of a 
specially-formatted paragraph in a reference section 

< SET_TEMPLATE_LIST > 

None 

Creates user-defined tags for the creation of a 
specially-formatted list in a reference section 

<SET_TEMPLATE_TABLE> 

None 

Creates user-defined tags for the creation of a 
specially-formatted table in a reference section 

<COMMAND> 

None 

Begins each new element to be referenced in the 
template; this is the default reference-element tag in 
the Command reference template 

<OVERVIEW> 

None 

Labels an overview of the reference-element 

<FORMAT> 

"Format" 

Labels the format of the reference-element's syntax 

<PARAMDEFLIST> 

"Parameters" 

Begins a definition list of the parameters or 
arguments associated with the reference-element 

<RESTRICTIONS> 

"Restrictions" 

Begins a list of zero or more restrictions on the 
reference-element's use 

< PROMPTS > 

"Prompts" 

Begins a list of the prompts associated with the 
reference-element 

<DESCRIPTION> 

"Description" 

Labels a reference-element description section 

<QUALDEFLIST> 

"Qualifiers" 

Begins a definition list of zero or more qualifiers 
associated with the reference-element 

<EXAMPLE_SEQUENCE> 

"Examples" 

Begins a sequence of one or more examples 

<SUBCOMMAND_SECTION> 

None 

Begins a section of subcommands within a 
Command section 

<SUBCOMMAND_SECTION_HEAD> 

None 

Specifies the heading for introductory text that 
precedes a subcommand section 

<SET_TEMPLATE_SUBCOMMAND> 

None 

Alters the name of the <SUBCOMMAND> tag, and 
optionally lets you specify that each use of that tag 
should not begin output on a new page 

<SUBCOMMAND> 

None 

Begins a new subcommand element to be described 
within a subcommand section 
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8.5.1 Sample SDML File of the Command template 

The following is an extended code example showing a VAX DOCUMENT 
SDML file that uses the Command template. 

<COMMAND_SECTION>(Using the SOFTWARE DoctypeWNEWPAGE) 

<SET_TEMPLATE_COMMAND>(DCL_COMMAND) 

<DCL_COMMAND>(APPEND) 

<0VERVIEW> 

Adds the contents of one or more specified input files to the end of the 
specified output file. 

<ENDOVERVIEW> 

<fORMAT> 

<fCMD>(APPEND) <FPARMS>(input-file-spec[,<hellipsis>] output-file-spec) 

<qUAL_LIST> (Command Qualifiers) 

<qPAIR>(/BACKUPX/CREATED) 

<qPAIR> (/BEFORE t=time]\/BEF0RE=T0DAY) 

<ENDqUAL_LIST> 

<qUAL_LIST> (Positional Qualifiers) 

<qPAIR> (/ALLOCATION=n\See text.) 

<qPAIR> (/[NO]CONTIGUOUSXNone.) 

<ENDqUAL_LIST> 

<ENDFORMAT> 

<RESTRICTIONS>(NONE) 

<PR0MPTS> 

<PR0MPT>(From:\input-file-spec [,<hellipsis>]) 

<PR0MPT>(To;\output-file-spec) 

<ENDPROMPTS> 

<PARAMDEFLIST> 

<PARAMITEM>(input-file-spec[,<hellipsis>]) 

<PARAMDEF>Specifies the names of one or more input files to be appended. 

<P> 

If you specify more than one input file, separate the specifications with 
either commas (,) or plus signs (+). 

Commas and plus signs are equivalent. All input files 

are appended, in the order specified, to the end of the output file. 

<P> 

You can use wildcard characters in the file specification(s). 

<PARAMITEM>(output-file-spec) 

<PARAMDEF> 

Specifies the name of the file to which the input files will be appended. 

<P> 

You must include at least one field in the output file specification. If you 
do not specify a device and/or directory, the APPEND command uses the current 
default device and directory. For other fields that you do not specify, the 
APPEND command uses the corresponding field of the input file specification. 

<P> 

If you use the asterisk wildcard character in any field(s) of the 

output file specification, the APPEND command uses the corresponding field of 

the input file specification. If you are appending more than one 

input file, APPEND uses the corresponding fields from the first input file. 

<ENDPARAMDEFLIST> 

<DESCRIPTION> 

The APPEND command is similar in syntax and function to the COPY command. 
Normally, the APPEND command adds the contents of one or more files 
to the end of an existing file without incrementing the version number. 

The /NEW_VERSION qualifier causes the APPEND command to create a new output 
file if no file with that name exists. 

<ENDDESCRIPTION> 
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<QUALDEFLIST>(Command Qualifiers) 

<qUALITEM> (/BACKUP) 

<QUALDEF> 

Selects files according to the dates of their most recent backup. 

This qualifier is relevant only 

when used with the /BEFORE or /SINCE qualifier. Use of the 

/BACKUP qualifier is incompatible with /CREATED, /EXPIRED, and /MODIFIED. 

The default is /CREATED. 

<QUALITEM>(/BEFORE[=time]) 

<QUALDEF> 

Selects only those files that are dated before the specified time. 

<P> 

You can specify 

either an absolute time or a combination of absolute and delta times. 

See Section <reference>(time_sec) for complete information on 
specifying time values. 

You can also use the 

keywords TODAY, TOMORROW, and YESTERDAY. If no time is specified, 

TODAY is assumed. 

<ENDqUALDEFLIST> 

<qUALDEFLIST> (Positional Qualifiers) 

<qUALITEM> (/ALL0CATI0N=n\) 

<qUALDEF> 

Forces the initial allocation of the output file to the number of 512-byte 
blocks specified as n. 

<P> 

This qualifier is valid in conjunction with the /NEW_VERSION qualifier. 

The allocation size is 

applied only if a new file is actually created. If a new file is created and 
you do not specify /ALLOCATION, the initial allocation of the output file is 
determined by the size of the input file(s). 

<qUALITEM>(/CONTIGUOUS\/NOCONTIGUOUS) 

<qUALDEF> 

Indicates whether the output file is contiguous, that is, whether the file 
must occupy consecutive physical disk blocks. 

<P> 

By default, the APPEND command creates an output file in the same format as 
the corresponding input file. If an input file is contiguous, the APPEND 
command attempts to create a contiguous output file, does not report an 
error if there is not enough space. If you append multiple input files of 
different formats, the output file might or might not be contiguous. Use the 
/CONTIGUOUS qualifier to ensure that the output file is contiguous. 

<ENDqUALDEFLIST> 

<EXAMPLE_SEqUENCE> 

<EXI><S>($) <U>(APPEND TEST.DAT NEWTEST.DAT) 

<EXTEXT> 

The APPEND command appends the contents of the file TEST.DAT from the default 
disk and directory to the file NEWTEST.DAT also located on the default disk 
and directory. 

<EXI>(WIDE)<S>($) <U>(APPEND/NEW_VERSION/LOG *.TXT T.SUM) 

<S> (‘/.APPEND-I-CREATED. Dl$: [MAL] T. SUM; 1 created) 

<S>(*/.APPEND-S-COPIED, Dl$: [MAL]A.TXT;2 copied to Dl$: [MAL]T.SUM; 1 (1 block)) 
<S>(*/.APPEND-S-APPENDED, Dl$: [MAL]B.TXT;3 appended to Dl$: [MAL]T.SUM; 1 (3 records)) 
<S>(y.APPEND-S-APPENDED, Dl$:[MAL]G.TXT;7 appended to Dl$:[MAL]T.SUM;1 (51 records)) 
<S>(y,APPEND-S-NEWFILES. 1 file created) 

<EXTEXT> 

The APPEND command appends all files with file types of TXT to a file named 
T.SUM. The /LOG qualifier requests a display of the specifications of each 
input file appended. If the file T.SUM does not exist, the APPEND command 
creates it, as the output shows. The number of blocks or records shown in the 
output refers to the SDML file and not to the target file total. 
<ENDEXAMPLE_SEqUENCE> 

<ENDCOMMAND_SECTION> 
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8.5.2 Sample Output File of the Command Template 

The following is the output from the extended code example in Section 8.5.1. 
Note that your own output may vary, depending on the SOFTWARE design 
under which you process the SDML file. 
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APPEND 


Adds the contents of one or more specified input files to the end of the 
specified output file. 


FORMAT APPEND input-file-spec[, ... 7 output-file-spec 


Command Qualifiers 

Defauits 

/BACKUP 

/CREATED 

/BEFORE[=time] 

/BEFORE=TODAY 

Positionai Qualifiers 

Defauits 

/ALLOCATIOIShn 

See text. 

/[NOJCONTIGUOUS 

None. 


restrictions 

None. 


prompts 

From: 

input-file-spec[, . . . ] 


To: 

output-file-spec 


PARAMETERS input-file-spec[, . . . ] 

Specifies the names of one or more input files to be appended. 


If you specify more than one input file, separate the specifications with either 
commas (,) or plus signs ( + ). Commas and plus signs are equivalent. All 
input files are appended, in the order specified, to the end of the output file. 

You can use wildcard characters in the file specification(s). 

output-file-spec 

Specifies the name of the file to which the input files will be appended. 

You must include at least one field in the output file specification. If you 
do not specify a device and/or directory, the APPEND command uses 
the current default device and directory. For other fields that you do not 
specify, the APPEND command uses the corresponding field of the input file 
specification. 

If you use the asterisk wildcard character in any field(s) of the output file 
specification, the APPEND command uses the corresponding field of the 
input file specification. If you are appending more than one input file, 
APPEND uses the corresponding fields from the first input file. 


DESCRIPTION The APPEND command is similar in syntax and function to the COPY 

command. Normally, the APPEND command adds the contents of one or 
more files to the end of an existing file without incrementing the version 
number. The /NEW_VERSION qualifier causes the APPEND command to 
create a new output file if no file with that name exists. 
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COMMAND /BACKUP 

QM Al ipijppc Selects files according to the dates of their most recent backup. This qualifier 

is relevant only when used with the /BEFORE or /SINCE qualifier. Use of 
the /BACKUP qualifier is incompatible with /CREATED, /EXPIRED, and 
/MODIFIED. The default is /CREATED. 

/BEFOREMime] 

Selects only those files that are dated before the specified time. 

You can specify either an absolute time or a combination of absolute and delta 
times. See Section 1.2 for complete information on specifying time values. 
You can also use the keywords TODAY, TOMORROW, and YESTERDAY. If 
no time is specified, TODAY is assumed. 


POSITIONAL 

QUALIFIERS 


/ALLOCATIOI\l=n 

Forces the initial allocation of the output file to the number of 512-byte blocks 
specified as n. 

This qualifier is valid in conjunction with the /NEW_VERSION qualifier. The 
allocation size is applied only if a new file is actually created. If a new file is 
created and you do not specify /ALLOCATION, the initial allocation of the 
output file is determined by the size of the input file(s). 

/CONTIGUOUS 

/NOCONTIGUOUS 

Indicates whether the output file is contiguous, that is, whether the file must 
occupy consecutive physical disk blocks. 

By default, the APPEND command creates an output file in the same format 
as the corresponding input file. If an input file is contiguous, the APPEND 
command attempts to create a contiguous output file but does not report 
an error if there is not enough space. If you append multiple input files of 
different formats, the output file might or might not be contiguous. Use the 
/CONTIGUOUS qualifier to ensure that the output file is contiguous. 


EXAMPLES 

Q $ APPEND TEST.DAT NEWTEST.DAT 

The APPEND command appends the contents of the file TEST.DAT from 
the default disk and directory to the file NEWTEST.DAT also located on the 
default disk and directory. 

2 $ APPEND/NEW_VERSION/LOG *.TXT T.SUM 

%APPEND-I-CREATED, Dl$:[MAL]T.SUM;1 created 

%APPEND-S-COPIED, Dl$:tMAL]A.TXT;2 copied to Dl$: [MAL]T.SUM;1 (1 block) 

"/.APPEND-S-APPENDED. Dl$: [MAL]B.TXT:3 appended to Dl$: [MAL]T.SUM; 1 (3 records) 

"/.APPEND-S-APPENDED. Dl$: [MAL]G.TXT:7 appended to Dl$: [MAL]T.SUM; 1 (51 records) 

"/.APPEND-S-NEWFILES. 1 file created 


The APPEND command appends all files with file types of TXT to a file 
named T.SUM. The /LOG qualifier requests a display of the specifications 
of each input file appended. If the file T.SUM does not exist, the APPEND 
command creates it, as the output shows. The number of blocks or records 
shown in the output refers to the SDML file and not to the target file total. 
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8.6 Using the Routine Template 

Table 8-3 summarizes the tags available in the Routine template, the default 
headings associated with them, and how they should be used. Such a table 
can be found at the beginning of each of the template reference sections. 
Chapter 14 contains the reference information on the tags listed in this table. 

Also included in this section are two subsections, which provide a sample 
use of the Routine template. You may find these sample files useful in 
understanding how the Routine template tags fit together into a whole. 

• Section 8.6.1 contains a SDML file listing of a sample use of the Routine 
template tags. 

• Section 8.6.2 contains a sample output file created using the SDML code 
listed in Section 8.6.1 

These samples describe the $ENQ and MTH$xSORT routines. These two 
subsections are intended only as sample files and should not be used as a 
source of reference for these routines. 


Table 8-3 Tags Available in the Routine Template in their Standard Order 


Tag Name 

Default 

Heading 

Template Usage 

<ROUTINE_SECTION> 

None 

Begins a Routine section 

<SET_TEMPLATE_ROUTINE> 

None 

Alters the default format of a Routine section 

<SET_TEMPLATE_HEADING> 

None 

Alters the default headings in a reference section 

<SET_TEMPLATE_PARA> 

None 

Creates user-defined tags for the creation of a 
specially-formatted paragraph in a reference section 

<SET_TEMPLATE_LIST> 

None 

Creates user-defined tags for the creation of a 
specially-formatted list in a reference section 

< SET_TEMPL ATE _T ABLE > 

None 

Creates user-defined tags for the creation of a 
specially-formatted table in a reference section 

< ROUTINE > 

None 

Begins each new element to be referenced in the 
template; this is the default reference-element tag in 
the Routine reference template 

<OVERVIEW> 

None 

Labels an overview of the reference-element 

<FORMAT> 

"Format" 

Labels the format of the reference-element's syntax 

<RETURNS> 

"Returns" 

Provides specific information about the attributes of the 
value returned by the routine 

<RETTEXT> 

None 

Provides general information about the attributes of the 
value returned by the routine 

<ARGDEFLIST> 

"Arguments" 

Begins a definition list of the arguments associated 
with the reference-element 

< DESCRIPTION > 

"Description" 

Labels a reference-element description section 

<RSDEFLIST> 

"Return Values" 

Begins a definition list of zero or more routine return 
status codes and their meanings 

<EXAMPLE_SEQUENCE> 

"Examples" 

Begins a sequence of one or more examples 
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8.6.1 Sample SDML File of the Routine Template 

The following is an extended code example showing a VAX DOCUMENT 
SDML file that uses the Routine template. 

<routine_section>(Using the SOFTWARE Doctype\\NEWPAGE) 
<set_template_routine>(VMS_ROUTINE\doublerunningheads) 

<VMS_ROUTINE>($ENQ\Enqueue Resource) 

<OVERVIEW>This is the brief description section. It contains one or 
two sentences of description of what the routine does. 

<ENDOVERVIEW> 

<F0RMAT> 

<frtn>($ENQ) <fargs>([efn]. Ikmode, Iksb, itmlst) 

<ENDFORMAT> 

<RETURNS>(cond_value\longword integer\read only\by value in RO) 

<RETTEXT>At times, it may be necessary to include a sentence or two 
here to further describe the nature of the information returned. 

<ENDRETTEXT> 

<ARGDEFLIST> 

<ARGITEM>(efn\cond_value\longword integer\read only\by value) 

<ARGDEF>Number of the event flag that is to be set when access is 
granted to the specified resource. If not specified, the default is 
event flag number 0. 

<ARGITEM>(lkmode\cond_value\longword integer\read only\by descriptor\varying string 
array descriptor) 

<ARGDEF>Name of lock mode requested. May be one of the following: 

<TABLE> 

<TABLE_SETUP>(2\17) 

<TABLE_HEADS>(Name of Lock Mode\Description) 

<TABLE_ROW>(LCK$K_NLMODE\Null lock mode) 

<TABLE_ROW>(LCK$K_CRMODE\Concurrent read mode) 

<TABLE_ROW>(LCK$K_CWMODE\Concurrent write mode) 

<ENDTABLE> 

<ARGITEM>(lksb\cond_value\longword integerXwrite only\by value) 

<ARGDEF>Address of the lock status block. The lock status block 
receives the final completion status and lock I.D., and optionally 
contains a lock value block. 

<ARGITEM>(itmlst) 

<ARGDEF> 

Item list specifying the lock information that IGETLKI is to return. The 
<variable>(itmlst) argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by a longword of 0. 

<line_art> 

31 15 0 

+-+ 

I item code I buffer length I 

+ - + - + 

I buffer address I 

+ - + - 

I return length address I 

+ - + 

<endline_art> 

<endargdeflist> 

<DESCRIPTION> 

This section contains the full, detailed description of the routine. 

It may contain tables and figures. There is no fixed size for this 
description section. 

<ENDDESCRIPTION> 

<RSDEFLIST> 

<RSITEM>(SS$_NORMAL\Indicates successful completion) 

<RSITEM>(SS$_ABORT\This description contains a full explanation of some of 
the possible causes for the abortion) 

<RSITEM>(SS$_DEADL0CK\Thi8 description contains a full explanation of 
some possible causes for the deadlock situation.) 

<ENDRSDEFLIST> 


8-43 







Using the SOFTWARE Doctype 


<EXAMPLE_SEqUENCE> 

<examples_intro> 

This section contains an example of the use of the routine. 

This section can also contain figures and tables. 

<ENDEXAMPLE_SEQUENCE> 

<VMS_ROUTINE>{MTH$xSQRT) 

<OVERVIEW>The square root procedure returns the square root of the 
input parameter. The input parameter may have one of four data types: 
F_Floating, D.Floating, G.Floating, and H.Floating, 

<endoverview> 

<F0RMAT> 

<ffunc>(MTH$SQRT\(x)) 

<ffunc>(MTH$DSQRT\(x)) 

<ffunc>(MTH$GSQRT\(x)) 

<ffunc>(MTH$HSQRT\(x)) 

<ENDFORMAT> 

<RETURNS>(cond_value\F_Floating, D_Floating. or G_Floating 
\write only\by value in RO) 

<RETURNS>(Readonly) 

<RETTEXT>The square roots of F_Floating, D_Floating, and G_Floating 
input parameters are returned by immediate value in RO and Rl. The 
square root of an H_Floating parameter is returned by reference 
in the output pareuneter <VARIABLE>(sqrt). 

<ENDRETTEXT> 

<ARGDEFLIST>(Argument) 

<ARGITEM>(x\cond_value\F_Floating,D_Floating, G_Floating. or H_Floating 
\read onlyXby reference) 

<ARGDEF>The number for which the square root is desired. 
<ARGITEM>(sqrt\cond_value\H_Floating\write only\by reference) 
<ARGDEF>The square root of the H_Floating parameter. 

<ENDARGDEFLIST> 

<description> 

This is a description of the MTH$xSQRT function. 

<enddescription> 

<endroutine_section> 


8.6.2 Sample Output File of the Routine Template 

The following is the output from the extended code example in Section 8.6.1. 
Note that your own output may vary, depending on the SOFTWARE design 
under which you process the SDML file. 
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ARGUMENTS efn 

VMS Usage: cond_value 
type: iongword integer 

access: read only 

mechanism: by value 

Number of the event flag that is to be set when access is granted to the 
specified resource. If not specified, the default is event flag number 0. 

Ikmode 

VMS Usage; cond_value 
type; iongword integer 

access; read only 

mechanism; by descriptor—varying string array descriptor 

Name of lock mode requested. May be one of the following: 


Name of Lock Mode 

Description 

LCK$K_NLMODE 

Null lock mode 

LCK$K_CRMODE 

Concurrent read mode 

LCK$K_CWMODE 

Concurrent write mode 


Iksb 

VMS Usage; cond—value 
type: Iongword integer 

access: write only 

mechanism: by value 

Address of the lock status block. The lock status block receives the final 
completion status and lock I.D., and optionally contains a lock value block. 
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itmist 

Item list specifying the lock information that $GETLKI is to return. The 
itmist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
a longword of 0. 


31 


I 


15 


item code I buffer length 


buffer address 


return length address 


0 

•+ 

I 

•+ 


+ 


DESCRIPTION 

This section contains the full, detailed description of the routine. It may 
contain tables and figures. There is no fixed size for this description section. 

RETURN 

VALUES 

SS$_NORMAL 

Indicates successful completion 

SS$_ABORT 

This description contains a full explanation of some 
of the possible causes for the abortion 


SS$_DEADLOCK 

This description contains a full explanation of some 
possible causes for the deadlock situation. 


EXAMPLES This section contains an example of the use of the routine. This section can 

also contain figures and tables. 
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MTH$xSQRT 


The square root procedure returns the square root of the input parameter. 
The input parameter may have one of four data types; F_Floating, D_ 
Floating, G_Floating, and H_Floating. 


FORMAT MTHSSQRTW 

MTHSDSQRTW 

MTHSGSQRTW 

MTHSHSQRTW 


RETURNS 


VMS Usage; 
type; 
access; 
mechanism; 


cond—value 

F_Floating, D_Floating, or G—Floating 
write only 
by value in RO 


RETURNS The square roots of F_Floating, D_Floating, and G—Floating input parameters 

are returned by immediate value in RO and Rl. The square root of an H_ 
Floating parameter is returned by reference in the output parameter sqrt. 


ARGUMENT 


X 

VMS Usage; cond—value 

type; F—Floating,D-Floating, G— Floating, or H—Floating 

access; read only 
mechanism; by reference 

The number for which the square root is desired. 

sqrt 

VMS Usage; cond—value 
type; H—Floating 

access; write only 
mechanism; by reference 

The square root of the H—Floating parameter. 


DESCRIPTION This is a description of the MTH$xSQRT function. 
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8.7 Using the Statement Template 

Table 8-4 summarizes the tags available in the Statement template, the 
default headings associated with them, and how they should be used. Such a 
table can be found at the beginning of each of the template reference sections. 
Chapter 14 contains the reference information on the tags listed in this table. 

Also included in this section are two subsections, which provide a sample 
use of the Statement template. You may find these sample files useful in 
understanding how the Statement template tags fit together into a whole. 

• Section 8.7.1 contains a SDML file listing of a sample use of the Statement 
template tags. 

• Section 8.7.2 contains a sample output file created using the SDML code 
listed in Section 8.7.1. 

These samples describe the RECORD statement and the MID$ function. This 
sample is intended only as an output sample and should not be used as a 
source of reference for these statements and functions. 


Table 8-4 Tags Available in the Statement Template in their Standard Order 


Tag Name 

Default 

Heading 

Template Usage 

<STATEMENT_SECTION> 

None 

Begins a Command Section 

< SET_TEMPL ATE .STATEMENT > 

None 

Alters the default format of a Statement section 

<SET_TEMPLATE_HEADING> 

None 

Alters the default headings in a reference section 

< SET-TEMPLATE _P AR A > 

None 

Creates user-defined tags for the creation of 
a specially-formatted paragraph in a reference 
section 

<SET_TEMPLATE_LIST> 

None 

Creates user-defined tags for the creation of a 
specially-formatted list in a reference section 

< SET-TEMPLATE _T ABLE > 

None 

Creates user-defined tags for the creation of a 
specially-formatted table in a reference section 

f <STATEMENT> ’ 1 

1 <FUNCTION> / 

None 

Begins each new element to be referenced in the 
template; this is the default reference-element tag 
in the Statement reference template 

<OVERVIEW> 

None 

Labels an overview of the reference-element 

<STATEMENT_FORMAT> 

"Format" 

Labels the format of the reference-element's syntax 

<DESCRIPTION> 

"Description" 

Labels a reference-element description section 

<EXAMPLE-SEQUENCE> 

"Examples" 

Begins a sequence of one or more examples 


’The use of braces indicates that the enclosed tag names are used interchangeably. VAX DOCUMENT 
provides two such names to improve the readability of your SDML file. 
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8.7.1 Sample SDML File of the Statement Template 

The following is an extended code example showing a VAX DOCUMENT 
SDML file that uses the Statement template. 


<statement_section>(Using the SOFTWARE DoctypeWNEWPAGE) 

<statement>(RECORD) 

<overview> 

The RECORD statement lets you name and define data structures in a 
BASIC program and provides the BASIC interface to the VAX Common Data 
Dictionary (CDD). You can use the defined RECORD name anywhere a 
BASIC data-type keyword is valid. 

<endoverview> 

<statement_format> 

<FCMD>(RECORD) <FPARMS>(rec-nam) 

<STATEMENT_LINE>(rec-component) 

<ellipsis> 

<FCMD>(END RECORD) <FPARMS>([ rec-nam ]) 

<construct_list>(rec-component;) 

<construct>(rec-component:)<list>(stacked\braces) 

<le>data-type rec-item [ . [ data-type ] rec-item ] 

<le>group-clause 

<le>variant-clause<endlist> 

<construct>(rec-item:)<list>(stacked\braces) 

<le>unsubs-vbl [ = int-const ] 

<le>array ( int-const,...) [ = int-const ] 

<le><keyword>(FILL) [ ( int-const ) ] [ = int-const ]<endlist> 
<construct>(group-clause:) 

<keyword>(GROUP) group-nam [ ( int-const,... ) ] 
<statement_line>(rec-component\indent) 

<ellipsis> 

<statement_line>(<keyword>(END GROUP) [ group-nam ]) 

<construct>(variant-clause:) 

<keyword>(VARIANT) 

<statement_line>(case-clause\indent) 

<ellipsis> 

<statement_line>(<keyword>(END VARIANT)) 

<construct>(case-clause:) 

<keyword>(CASE) 

<statement_line>( [ rec-component ]\indent) 

<endconstruct_list> 

<endstatement_format> 

<function>(MID$) 

<overview> 

The MID$ function extracts a specified substring from the middle of a 
string, leaving the main string unchanged. 

<endoverview> 

<statement_format> 

<fcmd> 0 <fparms>(str-vbl =<list>(stacked\braces) 

<le>MID 

<le>MID$ <endlist> <keyword>((str-exp, int-expl, int-exp2))) 

< endstat ement _f ormat > 

<endstatement_section> 


8-49 



Using the SOFTWARE Doctype 


8.7.2 Sample Output File of the Statement Template 

The following is the output from the extended code example in Section 8.7.1. 
Note that your own output may vary, depending on the SOFTWARE design 
under which you process the SDML file. 
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RECORD 

The RECORD statement lets you name and define data structures in a 
BASIC program and provides the BASIC interface to the VAX Common 
Data Dictionary (CDD). You can use the defined RECORD name anywhere a 
BASIC data-type keyword is valid. 

Format 

RECORD rec-nam 

rec-component 


END RECORD [ rec-nam ] 

data-type rec-item [, [ data-type ] rec-item ] 
rec-component: < group-clause 

. variant-clause 

unsubs-vbl [= int-const ] 

rec-item: array (int-const • • . )[ ^ int-const ] 

, FILL[(int-const)][= int-const] 

group-clause: GROUP group-nam [ (int-const • ■ • ) ] 

rec-component 


END GROUP [ group-nam ] 

variant-clause: VARIANT 

case-clause 


END VARIANT 

case-clause: CASE 

[ rec-component ] 
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MID$ 


The MID$ function extracts a specified substring from the middle of a 
string, leaving the main string unchanged. 


Format 


str-vbl = 


MID 

MID$ 


(str-exp, int-expl, int-exp2) 
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8.8 Using the Tag Template 

Table 8-5 summarizes the tags available in the Tag template, the default 
headings associated with them, and how they should be used. Such a table 
can be found at the beginning of each of the template reference sections. 
Chapter 14 contains the reference information on the tags listed in this table. 

Also included in this section are two subsections that provide sample uses of 
the Tag template. You may find these sample files useful in understanding 
how the Tag template tags fit together into a whole. 

• Section 8.8.1 contains a SDML file listing of a sample use of the Tag 
template tags. 

• Section 8.8.2 contains a sample output file created using the SDML code 
listed in Section 8.8.1 

This sample describes the < SYNTAX > tag. This sample is intended only as an 
output sample and should not be used as a source of reference for this tag. 


Table 8-5 Tags Available in the Tag Template in their Standard Order 


Tag Name 

Default 

Heading 

Template Usage 

<TAG_SECTION> 

None 

Begins a Tag Section 

<SET_TEMPLATE_TAG> 

None 

Alters the default format of a Tag section 

<SET_TEMPLATE_HEADING> 

None 

Alters the default headings in a reference section 

<SET_TEMPLATE_PARA> 

None 

Creates user-defined tags for the creation of a specially- 
formatted paragraph in a reference section 

<SET_TEMPLATE_LIST> 

None 

Creates user-defined tags for the creation of a specially- 
formatted list in a reference section 

<SET_TEMPLATE_TABLE> 

None 

Creates user-defined tags for the creation of a specially- 
formatted table in a reference section 

<SDML-TAG> 

None 

Begins each new element to be referenced in the 
template; this is the default reference-element tag in the 
Tag reference template 

<OVERVIEW> 

None 

Labels an overview of the reference-element 

<FORMAT> 

"Format" 

Labels the format of the reference-element's syntax 

<PARAMDEFLIST> 

"Arguments" 

Begins a definition list of the arguments associated with 
the reference-element 

< RELATED-TAGS > 

"Related Tags" 

Begins a list of zero or more tags related to the tag 
being described 

<TERMINATING^TAG> 

"Required 

Terminator" 

Labels the tag that terminates the tag being described 

<RESTRICTIONS> 

"Restrictions" 

Begins a list of zero or more restrictions on the 
reference-element's use 

<DESCRIPTION> 

"Description" 

Labels a reference-element description section 

<EXAMPLE-SEQUENCE> 

"Examples" 

Begins a sequence of one or more examples 
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8.8.1 Sample SDML File of the Tag Template 

The following is an extended code example showing a VAX DOCUMENT 
SDML file that uses the Tag template. 

<TAG_SECTION>(Using the SOFTWARE Doctype\\NEWPAGE) 

<SDML_TAG>(SYNTAX) 

<0VERVIEW> 

Allows you to use special characters to describe language 
syntaxes. 

<ENDOVERVIEW> 

<F0RMAT> 

<FTAG>(SYNTAX\<LIST>(STACKED\braces) 

<LE>heading-text [<ARG_SEP>WIDE] 

<LE>WIDE<ENDLIST>\OPTIONAL) 

<ENDFORMAT> 

<PARAMDEFLIST> 

<PARAMITEM>(heading-text) 

<PARAMDEF>Specifies a heading. The doctype controls the font used to 
display the heading. By default, this tag has no heading. You may wish to create 
a heading using the <TAG>(SYNTAX_DEFAULT_HEAD) tag. 

<PARAMITEM>(WIDE) 

<PARAMDEF>Specifies that the syntax statement may exceed the normal right 
margin of the text. If you are using doctype designs that indent 
the text body, a wide syntax example will extend into the left margin. 

<ENDPARAMDEFLIST> 

<RELATED_TAGS> 

<RELATED_TAG>(display) 

<RELATED_TAG>(syntax_default_head) 

<RELATED_ITEM>The global <TAG>(CODE_EXAMPLE) tag 
<RELATED_ITEM>The global <TAG>(FORMAT) tag 
<ENDRELATED_TAGS> 

<RESTRICTIONS> 

You cannot use tab characters, 

index tags (such as the <TAG>(x) and <TAG>(Y) tags, 

or text element tags (such as <TAG>(p), <TAG>(list), or <TAG>(note)) 

within this type of example. 

<ENDRESTRICTIONS> 

<TERMINATING_TAG>(ENDSYNTAX) 

<DESCRIPTION> 

The <TAG>(SYNTAX) tag allows you to accurately describe language 
syntax. Languages can Include programming languages, command 
languages, application defined languages, and so forth. This tag also 
separates the syntax example from the remaining text, retains blank 
spaces and open lines, and labels the example (if you specified one) 
using a doctype-specific font different from the current text font. 

<ENDDESCRIPTION> 

<EXAMPLE_SEQUENCE>(EXAMPLE) 

<EXC><LITERAL><P>The COPY command has the following syntax: 

<SYNTAX> 

COPY input-file output-file 

<ENDSYNTAX> 


<ENDLITERAL> 

<EXTEXT> 

This example may produce the following output; 
<P> 

The COPY command has the following syntax: 
<SYNTAX> 

COPY input-file output-file 

<ENDSYNTAX> 

<ENDEXAMPLE_SEQUENCE> 
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8.8.2 Sample Output File of the Tag Template 

The following is the output from the extended code example in Section 8.8.1. 
Note that your own output may vary, depending on the SOFTWARE design 
under which you process the SDML file. 
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<SYNTAX> 

Allows you to use special characters to describe language syntaxes. 

FORMAT 

<SYNTAX> f( i heading-text [\ WIDE] 1 17 
' 1 WIDE i ■ 

ARGUMENTS 

heading-text 

Specifies a heading. The doctype controls the font used to display the 
heading. By default, this tag has no heading. You may wish to create a 
heading using the < SYNTAX _DEFAULT_HEAD > tag. 

WIDE 

Specifies that the syntax statement may exceed the normal right margin of 
the text. If you are using doctype designs that indent the text body, a wide 
syntax example will extend into the left margin. 

related tags 

• < DISPLAY > 

• <SYNTAX_DEFAULT_HEAD> 

• The global < CODE-Example > tag 

• The global <FORMAT> tag 

restrictions 

You cannot use tab characters, index tags (such as the <x> and <Y> tags, 
or text element tags (such as <P> , <LIST> , or <NOTE> ) within this type of 
example. 

required 

terminator 

<ENDSYNTAX> 

DESCRIPTION 

The < SYNTAX > tag allows you to accurately describe language syntax. 
Languages can include programming languages, command languages, 
application defined languages, and so forth. This tag also separates the 
syntax example from the remaining text, retains blank spaces and open lines, 
and labels the example (if you specified one) using a doctype-specific font 
different from the current text font. 
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EXAMPLE 


<P>The COPY command has the following syntax: 
<SYNTAX> 

COPY input-file output-file 

<ENDSYNTAX> 


This example may produce the following output: 
The COPY command has the following syntax: 

COPY input-file output-file 
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This chapter provides reference information on the tags specific to the 
LETTER doctype. These tags allow you to create memos and letters. In 
general, tag names prefixed with MEMO— are used to create memos; the 
other tags are used to create letters or to create headings in either memos 
or letters. You can use these tags in any sequence to create your own letter 
and memo formats. Chapter 3 provides the tutorial information on the use of 
these tags. 

The LETTER doctype supports all of the VAX DOCUMENT global tags with 
the following exceptions: 

• <APPENDIX> 

• < CHAPTER > 

• <FRONT_MATTER> 

• <HEAD1> through <HEAD6> 

• <PART_PAGE> 

Although the LETTER doctype does not support the global numbered 
heading tags ( <HEADn> ), it does support the global unnumbered heads 
( <SUBHEAD1> and <SUBHEAD2> ). 

See the VAX DOCUMENT User Manual, Volume 1 for more information on the 
global tags. 
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<CC> 


<cc> 

Lists the name of someone who is to receive a copy of a memo or letter. 

FORMAT 

<CC> (receiver-name) 

ARGUMENTS 

receiver-name 

Specifies the name of someone who should receive a copy of the memo or 
letter. 

related tags 

• <CCLIST> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <CC> tag lists a single name of someone who is to receive a copy of 
a memo or letter. This tag can be used by itself or within the context of the 
<CCLIST> tag. 

If the <CC> tag is used alone, it places the heading "cc:" on the left margin 
and places the receiver-name argument on the same line as that heading. 

If the <CC> tag is used within the context of the <CCLIST> tag, it places 
the text of the receiver-name argument in the same location as when it is used 
without the <CCLIST> tag, but omits the heading. 


EXAMPLES The following example shows the beginning of a letter using the <CCLIST> 

tag with the <CC> tag. 


<MEM0_FR0M>(Bob Smith\Harvard University) 

<MEM0_T0>(Carol Jones) 

<CCLIST> 

<CC>(Mr. A. Square) 

<CC>(Ms. B. Box) 

<ENDCCLIST> 

<SUBJECT>(Ted Fields and Alice Johnson) 

<P> 

This is some text to show you where the text begins. 


The following example shows the beginning of a letter using only the <CC> 
tag. 
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<CC> 


<MEM0_FR0M>(Bob Smith\Harvard University) 

<MEM0_T0>(Carol Jones) 

<CC>(Mr. A. Square) 

<SUBJECT>(Ted Fields and Alice Johnson) 

<P> 

This is some text to show you where the text begins. 
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<CCLIST> 


<CCLIST> 

Begins a list of persons to whom you want to send a copy of a memo or 
letter. 

FORMAT 

<CCLIST> 

ARGUMENTS 

None. 

related tags 

• <cc> 

• <DISTLIST> 

restrictions 

None. 

required 

terminator 

<ENDCCLIST> 

DESCRIPTION 

The <CCLIST> tag begins a listing of one or more persons' names who are 
to receive a copy of a memo or letter. The <CCLIST> tag places the heading 
"cc:" on the left margin. The names are specified using the <CC> tag. 

The names are formatted such that the argument to the first <CC> tag is 
placed on the same line as the heading, and the text arguments associated 
with any following <CC> tags are placed immediately beneath the argument 
to the first <CC> tag. 


EXAMPLE The following example shows the beginning of a letter using the <CCLIST> 

tag with the <cc> tag. 


<MEM0_FR0M>(Bob\Harvard University) 

<MEM0_T0>(Carol) 

<CCLIST> 

<CC>(Mr. A. Square) 

<CC>(Ms. B. Box) 

<ENDCCLIST> 

<SUBJECT>(Ted and Alice) 

<P> 

This is some text to show you where the text begins. 


<CLOSING>(Best Wishes,\Bob\Chairman, QZZA, Inc.) 
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<CHEAD> 


<CHEAD> 

Creates a centered heading. 

FORMAT 

<CHEAD> (heading-text [\ symbol-name]) 

ARGUMENTS 

heading-text 

Specifies the text of the centered heading. 

symbol-name 

Specifies a symbol to identify the heading associated with the <CHEAD> 
tag. Use this argument if you are planning to reference this heading by its 
title elsewhere in the document. This argument is provided so that you can 
reference unnumbered headings. 

The symbol-name argument can be any text string of 31 characters or less 
without spaces. This text must contain only the letters A through Z, the 
numbers 0 through 9 and the underscore (_) character. The symbol-name 
may not begin with an underscore character. 

related tags 

• <HEAD> 

• < SECTION > 

• The global < center > tag 

• The global <subheadi> tag 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <CHEAD> tag creates a centered unnumbered heading. The 
capitalization of the letters in this heading is retained in the output as typed. 

If you need to use a primary heading, use the <head> or <section> tags. 
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<CHEAD> 


EXAMPLE The following example shows how to use the <CHEAD> tag and the 

<HEAD> tags to create unnumbered headings. 

<HEAD>(How to Write a Letter) 

<P> 

The first thing that you should do in writing a letter is to get 
a clean piece of paper and a well-sharpened pencil. 

<CHEAD>(Getting the Piece of Paper) 

<p> 

You can buy clean paper in most major supermarkets, department stores, 
and hardware stores, You should try to get ruled paper so that 
your letter will be neat and easy to read. 
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<CLOSING> 


<CLOSING> 

Specifies the closing of a letter. 

FORMAT 

<CLOSING> (closing-line-1 [\ closing-line-2] . . . 

[ \ closing-line-5 ]} 

ARGUMENTS 

closing-line-n 

Specifies one to five lines of text that close a letter and name the sender of 
the letter. 

related tags 

• <SALUTATION> 

• <FROM_ADDRESS> 

• <TO_ADDRESS> 

• <MEMO_FROM> 

• <MEMO_TO> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The < CLOSING > tag lets you label one to five lines of text as the closing of 
your letter. The closing-line-n arguments are all placed to the right of the 
center of the page. Four blank lines are placed between the first and the 
second closing-line-n arguments to allow room for the signature of the writer 
of the letter. 

Typically, the first argument is the name of the author, and the second 
through fifth arguments are information about the author (for example, the 
author's position, title, and so on). 

EXAMPLE 

The following example shows the closing of a letter using the < CLOSING > 
tag. 


This is the end of the letter text. 
<CLOSING>(Best Wishes,\Bob\Chairman, QZZA, Inc.) 
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LETTER Doctype Tag Reference 

<DISTLIST> 


<DISTLIST> 

Begins a list of persons to whom you want to distribute a memo or letter. 

FORMAT 

<DISTLIST> 

ARGUMENTS 

None. 

related tags 

• <CCLIST> 

restrictions 

None. 

required 

terminator 

<ENDDISTLIST> 

DESCRIPTION 

The <DISTLIST> tag begins a list of persons to whom you want to distribute 
a memo or letter. The <DISTLIST> tag places the heading "Distribution:" 
on the left margin. The names of the people on the distribution list appear 
beneath the heading, formatted exactly as you entered them between the 
<DISTLIST> and <ENDDISTLIST> tags. 

The <DISTLIST> tag retains all spacing and capitalization exactly as entered. 
This lets you place asterisks before certain names, indent certain names, and 
so on. 

EXAMPLE 

The following example shows the end of a letter using the <DISTLIST> tag. 
The format of the text within the context of the <DISTLIST> tag will be 
retained exactly as entered, just as the global <CODE_EXAMPLE> tag retains 
formatting exactly as entered. 


<DISTLIST> 

*Bob 

Carol *Ted Alice 
Pete Jon *Art 
* - Indicates primary reviewer 
<ENDDISTLIST> 
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LETTER Doctype Tag Reference 
<FROM_ADDRESS> 

<FROM_ADDRESS> 


Places the name and address of the sender of a letter, flush left near the 
right margin. 

FORMAT 

<FROM_ADDRESS> (address-line-1 

[ \ address-line-2] . . . 

[\ address-line-5]) 

ARGUMENTS 

address-line-n 

Specifies one to five lines of text that contain the name and address of the 
sender of the letter. 

related tags 

• <TO_ADDRESS> 

• <MEMO_FROM> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <FROM_ADDRESS> tag is used to format the text used to label the sender 
of a business letter, a personal letter, or a memo. The < FROM-ADDRESS > 
tag outputs one to five lines of text based on the number of address-line 
arguments specified. Each of these arguments is placed flush left on a new 
line near the right margin. 


Alternatively, you can use the <MEMO_FROM> tag to specify this same 
information, but in a different format. The <MEMO_TO> tag places this 
same information flush left next to the heading "From:," which is on the left 
margin. See the description of the <memo_FROM> tag in this chapter for 
more information on that tag. 
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LETTER Doctype Tag Reference 

<FROM_ADDRESS> 


EXAMPLE The following example shows the beginning of a letter that uses the <FROM_ 

ADDRESS> tag. 

<FROM_ADDRESS>(Bob Smith\Harvard University\Cambridge, MA) 

<TO_ADDRESS>(Carol Jones\World Wide Wickets CoASeattle, WA) 

<SUBJECT>(Ted and Alice) 

<SALUTATION>(Hi Carol.) 

<P> 

This is the text of the letter 


<CLOSING>(Best Wishes,\Bob Smith\Chairman, QZZA, Inc.) 
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LETTER Doctype Tag Reference 

<HEAD> 

<HEAD> 

Creates a main heading on the left of the page. 

FORMAT 

<HEAD> (heading-text [\ symbol-name]) 

ARGUMENTS 

heading-text 

Specifies the text of the heading 

symbol-name 

Specifies the symbol to identify the heading associated with the <HEAD> 
tag. Use this argument if you are planning to reference this heading by its 
title elsewhere in the document. This argument is provided so that you can 
reference unnumbered headings. 

The symbol-name argument can be any text string of 31 characters or less 
without spaces. This text must contain only the letters A through Z, the 
numbers 0 through 9 and the underscore (_) character. The symbol-name 
may not begin with an underscore character. 

related tags 

• <CHEAD> 

• <SECTION> 

• The global <SUBHEAD1> tag 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <HEAD> tag creates an unnumbered heading on the left side of the 
page. Other tags in the LETTER doctype that prod^uce unnumbered headings 
are the doctype-specific < section > and <chead> tags, and the global 
<suBHEADi> and <subhead2> tags. 


See the appropriate reference descriptions in this chapter for more information 
on the LETTER doctype tags, or see the VAX DOCUMENT User Manual, 
Volume 1 for information on any of the global tags. 
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<HEAD> 


EXAMPLE The following example shows how to use the <HEAD> tag and the 

<CHEAD> tags to create unnumbered headings. 

<HEAD>(How to Write a Letter) 

<P> 

The first thing that you should do in writing a letter is to get 
a clean piece of paper and a well-sharpened pencil. 

<CHEAD>(Getting the Piece of Paper) 

<P> 

You can buy clean paper in most major supermarkets, department stores, 
and hardware stores. You should try to get ruled paper so that 
your letter will be neat and easy to read. 
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<MEIVIO_DATE> 



EXAMPLES The following example shows the beginning of a memo using the < MEMO- 

DATE > tag with the global <DATE> tag as an argument. 


<MEMO_HEADER> 

<MEM0_FR0M>(Bob\Dept. of English) 

<MEMO_TO>(Carol\Dept. of Archeology) 

<MEMO_LINE>(Req No.\ARC-132) 

<MEM0_DATE>(<DATE>) 

<SUBJECT>(Awards for Ted and Alice) 

<P> 

This is the text of the memo. 

The following example shows the beginning of a memo using the <MEMO_ 
DATE> tag with a text string as an argument. 
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<MEMO_DATE> 


<MEMO^HEADER> 

<MEM0_FR0M>(Bob Smith\Dept. of English) 
<MEM0_LINE>(Phone:\9-5151) 

<MEM0_T0>(Carol Jones\Dept. of Archeology) 
<MEM0_LINE>(Req No.\ARC-132) 

<MEM0_DATE>(January 1. 1987, 10:00 pm) 
<SUBJECT>(Awards for Ted and Alice) 

<P> 

This is the text of the memo. 
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<MEMO_FROM> 


<MEMO_ 

FROM> 

Places the name and address of the sender of a memo flush left on the left 
margin with a heading of "From:." 

FORMAT 

<MEMO_FROM> (address-line-1 

[ \ address-line-2] . . . 

[ \ address-line-5]) 

ARGUMENTS 

address-line-n 

Specifies one to five lines of text that contain the name and address of the 
sender of the memo. 

related tags 

• <MEMO_TO> 

• <FROM_ADDRESS> 

restrictions 

None. 

required 

terminator 

None. 


DESCRIPTION This tag is used to format the text used to identify the sender of a memo. 

The <MEMO_FROM> tag outputs a heading of "From:" on the left margin, 
and places the text from its first argument on this same line. Each additional 
argument is formatted so its text begins directly beneath the beginning 
character of the first address-line-n argument. 

Alternatively, you can use the <from_address> tag to specify this same 
information, but in a different format. The <FROM_ADDRESS> tag places the 
information on the right margin, with each argument flush left. The <from_ 
ADDRESS > tag does not create the heading "From:." 

In general, the <memo_from> tag is more appropriate for memos and the 
<FROM_ADDRESS> tag is more appropriate for letters; however, either tag 
can be used in either format. See the description of the < FROM-ADDRESS > 
tag in this chapter for more information on that tag. 
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LETTER Doctype Tag Reference 

<MEMO_FROM> 


EXAMPLE 


The following example shows a typical beginning of a memo using the 
<MEMO_FROM> tag. 


<MEMO_HEADER> 

<MEM0_FR0M>(Bob Smith\Dept. of English) 
<MEM0_T0>(Carol Jones\Dept. of Archeology) 
<MEMO_LINE>(Req No.\ARC-132) 
<MEMO_DATE>(<DATE>) 

<SUBJECT>(Ted and Alice) 

<P> 

This is the text of the memo. 


<CL0SING>(Yours Truly,\Bob Smith\CE0, Harvard English Dept) 




LETTER Doctype Tag Reference 

<MEMO_HEADER> 


<MEMO_HEADER> 

Centers the heading "Interoffice Memorandum" in bold letters on the page. 

FORMAT 

<MEMO_HEADER> 

ARGUMENTS 

None. 

related tags 

• <MEMO_TO> 

• <MEMO_FROM> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The < MEMO-HEADER > tag automatically centers the heading "Interoffice 
Memorandum" in bold letters on the page. This tag accepts no arguments. 

EXAMPLE 

The following example shows a typical beginning of a memo using the 
<MEMO_HEADER> tag. 


<MEMO_HEADER> 

<MEM0_FR0M>(Bob Smith\Dept. of English) 
<MEM0_T0>(Carol Jones\Dept. of Archeology) 
<MEM0_DATE>(<DATE>) 

<SUBJECT>(Ted and Alice) 

<P> 

This is the text of the memo. 
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LETTER Doctype Tag Reference 

<MEMO_LINE> 


<MEMO_LINE> 

Lets you create your own titled informational lines. 

FORMAT 

<MEMO-.LINE> (heading-text \ memo-line-1 

[ \ memo-line-2] . . . 

[ \ memo-line-5]) 

ARGUMENTS 

heading-text 

Specifies the heading of the <MEMO_LiNE> , which is placed on the left 
margin. This text must be no more than seven characters and will have a 
colon appended to it. 

memo-line-n 

Specifies one to five lines of text that follow the heading-text argument. The 
first line is formatted on the same line as the heading text and the following 
lines are formatted beneath it one to a line. 

related tags 

• <FROM_ADDRESS> 

• < MEMO-DATE > 

• <MEMO_FROM> 

• <MEMO_TO> 

restrictions 

The heading-text argument cannot be more than seven characters without 
over-writing the text specified to the memo-line-1 argument. 

required 

terminator 

None. 

DESCRIPTION 

The < MEMO-LINE > tag lets you define your own single-line heading and 
place one to five lines of information after it. For example, you could define 
a heading of "Corp" and follow it with the name of the corporation to whom 
you are sending the letter or memo. 

The <MEMO-LlNE> tag creates a heading on the left margin. You specify 
this heading with the heading-text argument. Whatever text is supplied as this 
argument will have a colon appended to it upon output. 

This is followed, on the same line, by the text specified with the memo- 
line-1 argument. Text of any other memo-line-n arguments is formatted, one 
argument to a line, beneath the first argument. 

See the description of the <MEMO_FROM> tag to compare the output of the 
<MEMO-LINE > tag with other tag formats. 
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<MEMO_LINE> 


EXAMPLE The following example shows how the <MEMO_LlNE> tag can be used to 

create an additional line of information with a heading. In this example, the 
heading "Corp:" is created with the text following it being "Drofnats Ltd." 
Note that the heading-text argument does not exceed seven characters; note 
also that even though a colon is desired in the heading it is not specified as 
part of the heading-text argument. 

<MEMO_HEADER> 

<MEM0_FR0M>(J. SimpsonXAccounting Consultant) 

<MEMO_LINE>(Corp\Drofnats Ltd.) 

<MEM0_T0>(Mr. Smith\ACME Corporate Accounting) 

<MEM0_DATE> (March 1.7, 1986) 

<CC>(Departmental Distribution) 

<SUBJECT>(Conference Report) 

<P>This conference was hosted by Numbers Inc. in Seattle, Washington 
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<MEMO_TO> 


<MEI\/IO_ 

TO> 

Places the name and address of the receiver of a memo flush left on the 
left margin with a heading of "To:." 

FORMAT 

<MEMO_TO> (address-line-1 [\ address-line-2] . . . 

[ \ address-line-5]) 

ARGUMENTS 

address-line-n 

Specifies one to five lines of text that contain the name and address of the 
receiver of the memo. 

related tags 

• <MEMO_FROM> 

• <TO_ADDRESS> 

restrictions 

None. 

required 

terminator 

None. 


DESCRIPTION This tag is used to format the text used to identify the receiver of a memo. 

The <MEMO_TO> tag outputs a heading of "To:" on the left margin and 
places the text from its first argument on this same line. Each additional 
argument is formatted so its text begins directly beneath the beginning 
character of the first address-line-n argument. 

Alternatively, you can use the <TO_ADDRESS> tag to specify this same 
information but in a different format. The <TO_ADDRESS> tag places this 
same information on the left margin with each argument flush left. The 
<TO_ADDRESS> tag does not create a heading. 

In general, the <MEMO_TO> tag is more appropriate for memos and the 
<TO_ADDRESS> tag is more appropriate for letters; however, either tag may 
be used in either format. See the description of the <TO_address> tag in 
this chapter for more information on that tag. 
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<MEMO_TO> 


EXAMPLE 


The following example shows a typical beginning of a memo using the 
<MEMO_TO> tag. 


<MEMO_HEADER> 

<MEM0_FR0M>(Bob Smith\Dept. of English) 
<MEM0_T0>(Carol Jones\Dept. of Archeology) 
<SUBJECT>(Ted and Alice) 

<P> 

This is the text of the memo. 
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<SALUTATION> 


<SALUTAT10N> 

Specifies the salutation for the letter. 

FORMAT 

<SALUTATION> (greeting-text) 

ARGUMENTS 

greeting-text 

Specifies the text of the salutation, including any punctuation. 

related tags 

• <FROM_ADDRESS> 

• <TO_ADDRESS> 

• <MEMO_FROM> 

• <MEMO_TO> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The < SALUTATION > tag lets you select the opening greeting of your letter or 
memo, such as "Dear Sirs:." This text begins at the left margin. 

Any punctuation that is part of the salutation (such as a comma, colon, or 
semicolon) must be specified as part of the greeting-text argument. 

EXAMPLE 

The following example shows a use of the < SALUTATION > tag in the 
beginning of a letter. Note that you must provide any needed punctuation, 
such as the comma after "Hi Carol" in this example. 


<FROM_ADDRESS>(Bob Smith\Harvard UniversityN Cambridge, MA) 
<TO_ADDRESS>(Carol Jones\World Wide Wickets CoASeattle, WA) 
<SUBJECT>(Ted and Alice) 

<SALUTATION>(Hi Carol,) 

<P> 

This is the text of the letter. 
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LETTER Doctype Tag Reference 

<SUBJECT> 


<SUBJECT> 

Specifies the subject of a memo or letter and places this information with 
a heading of "Subject:" at the left margin. 

FORMAT 

<SUBJECT> (subject-text) 

ARGUMENTS 

subject-text 

Specifies the text that describes the subject of a memo or letter. 

related tags 

• <FROM_ADDRESS> 

• <MEMO_FROM> 

• <MEMO_TO> 

• < MEMO-LINE > 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

This tag is used to create a subject line with a heading. The < SUBJECT > tag 
places the heading "Subject:" at the left margin and places the text from the 
subject-text argument on that same line. 

EXAMPLE 

The following example shows a use of the < SUBJECT > tag in the beginning 
of a letter. Note that this tag can also be used in a memo. 


<FROM_ADDRESS>(Bob Smith\Harvard University\Cambridge, MA) 
<TO_ADDRESS>(Carol Jones\World Wide Wickets CoASeattle, WA) 
<SUBJECT>(Ted and Alice) 

<SALUTATION>(Hi Carol.) 

<P> 

This is the text of the letter. 
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<TO_ADDRESS> 


<TO_ADDRESS> 

Places the name and address of the receiver of a letter flush left on the left 
margin. 

FORMAT 

<TO_ADDRESS> (address-line-1 

[\ address-line-2] . . . 

[ \ address-line-5]) 

ARGUMENTS 

address-line-n 

Specifies one to five lines of text that contain the name and address of the 
receiver of the letter. 

related tags 

• <FROM_ADDRESS> 

• <MEMO_TO> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

This tag is used to format the text used to identify the receiver of a letter. The 
<TO_ADDRESS> tag outputs one to five lines of text, based on the number of 


address-line arguments specified. Each argument is placed flush left on a new 
line at the left margin. 

Alternatively you can use the <MEMO_TO> tag to specify this same 
information but in a different format. The <MEMO_TO> tag places this 
same information flush left next to the heading "To:" on the left margin. See 
the description of the <MEMO_TO> tag in this chapter for more information. 

EXAMPLE 

The following example shows a typical beginning of a letter using the <TO_ 
ADDRESS > tag. 


<FROM_ADDRESS>(Bob Smith\Harvard University\Cambridge, MA) 
<TO_ADDRESS>(Carol Jones\World Wide Wickets CoASeattle, WA) 
<SUBJECT>(Ted and Alice) 

<SALUTATION>(Hi Carol,) 

<P> 

This is the text of the letter. 
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MILSPEC Doctype Tag Reference 


This chapter contains the reference information on all the tags available 
within the MILSPEC doctype. The MILSPEC doctype is a full implementation 
of the United States Military Specification Standard MIL-STD-490A. 

Chapter 5 contains a tutorial on how to use these tags. 

The MILSPEC doctype accepts the full range of VAX DOCUMENT global 
tags, with the exception of the <PART> and <part_page> tags. See the 
VAX DOCUMENT User Manual, Volume 1, for more information on global 
tags. 

The MILSPEC doctype also provides additional doctype-specific tags that 
let you create the front matter of your document in accordance with the 
MIL-STD-490A standard. These tags are described alphabetically in this 
chapter. 
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MILSPEC Doctype Tag Reference 

<SET_APPENDIX_NUMBER> 


<SET_APPENDIX_NUMBER> 

Overrides the default appendix Roman numeral assigned to an appendix by 
VAX DOCUMENT. 

FORMAT 

<SET_APPENDIX_NUMBER> (Roman-number- 

integer) 

ARGUMENTS 

Romari’number-integer 

Specifies an integer that evaluates to the Roman numeral for the appendix. 
This argument must be an integer greater than zero. 

related tags 

• The global <appendix> tag 

• The global <set_appendix_letter> tag 

• The global <seT-CHAPTER-NUMBER> tag 

restrictions 

This tag should not be used in a file that uses a book build profile or that 
uses the /PROFILE qualifier during processing. If either of these conditions 
occur, a warning message is issued and the <seT-APPENDIX_number> tag is 
ignored. 

required 

terminator 

None. 


DESCRIPTION Use the <set_appendix_number> tag to override the default appendix 

Roman numeral created by VAX DOCUMENT. 


The <SET_APPENDIX-NUMBER > tag resets the current appendix Roman 
numeral to the integer you specify as the Roman-number-integer. If you 
specified 4 as the Roman numeral integer, VAX DOCUMENT would set the 
appendix number to "IV." 

Place the <set_appendix_number> tag in your SDML file before the 
< APPENDIX > tags you want it to affect because the <set_appendix_ 
NUMBER> tag affects only the <appendix> tags that follow it. 

The new appendix number you specify resets the numbering for all following 
appendixes. For example, if you set the appendix number to 2, the next 
appendix will be numbered "11," the appendix following that appendix will be 
numbered "HI," and so on. 

The < SET-APPENDIX_NUMBER> can be used multiple times in an SDML file. 
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MILSPEC Doctype Tag Reference 

<SET_APPENDIX_NUMBER> 


EXAMPLE In the following example the appendix is explicitly set to IV using the < SET- 

APPENDIX-NUMBER > tag. This will cause any subsequent appendixes to be 
numbered beginning with the Roman numeral IV unless another < SET- 
APPENDIX-NUMBER > tag is used. 

<SET_APPENDIX_NUMBER>(4) 

<APPENDIX>(Run-time FunctionsXfunctions_ap) 

<P> 

The following functions... 
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MILSPEC Doctype Tag Reference 
<SIGNATURE_LINE> 


<SIGNATURE_LINE> 

Creates up to two rules on a line and places a name below each rule; each 
rule is used as a signatory line for the person listed below it. 

FORMAT 

<SIGNATURE_LINE> ([name-1 ] \ [name-2]) 

ARGUMENTS 

name-n 

Specifies the name or title of the person who is to sign on the previous line. 
These names and lines are output in two columns, if one of these arguments 
is not specified, neither the name nor the signature line is output in that 
column. 

related tags 

• <SIGNATURE_LIST> 


<SPECIFICATION_INFO> 

< SPEC-TITLE > 

< SUBTITLE > 

The global <front_matter> tag 
The global <TITLE_PAGE> tag 


restrictions 

Valid only within the context of the < SIGNATURE-LIST > tag. 

required 

terminator 

None. 

DESCRIPTION 

Use the <SIGNATURE_LINE> tag to create up to two rules with the name 
of a person listed below each rule. This tag creates signature lines within a 
signature list with the name of the person placed below each signature line. 

The signature list has a two-column format; if you omit a name in either 
column, no name (or rule) is placed in that column. 
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MILSPEC Doctype Tag Reference 

<SIGNATURE_LINE> 


EXAMPLE 


<TITLE_PAGE> 


<SIGNATURE_LIST> 

<SIGNATURE_LINE>(Mr. A. Baloo\Ms. C. Dee) 
<SIGNATURE_LINE>(John Doe\ ) 
<SIGNATURE_LINE>( \Mrs. Smith) 
<SIGNATURE_LIST> 


The following example shows a signature list with two names in the first row 
of signatures, a single name in the left column of the second row, and a name 
in the right column of the third row. 
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<SIGNATURE_LIST> 


<SIGNATURE_UST> 


Begins a two-column listing of signature lines on the title page of a 
document and supplies headings for each of those columns. 

FORMAT 

<SIGNATURE_UST> (col-heading-1 

\ col-heading-2) 

ARGUMENTS 

col-heading-n 

Specifies the heading for the column of signatures. These headings are 
required. 

related tags 

• <SPECIFICATION_INFO> 


<SPEC_TITLE> 

< SIGNATURE _LINE > 

<SUBTITLE> 

The global <title_page> tag 
The global <front_matter> tag 


required 

terminator 

<ENDSIGNATURE_LIST> 

restrictions 

Valid only within the context of the global <TITLE_PAGE> tag. 

DESCRIPTION 

The <SIGNATURE_LIST> tag begins a two-column listing of signatures on 
the title page of a document. This tag requires two arguments, which are the 
headings to be placed over each of the signature-line columns. 

This tag enables the < signature _line> tag to specify each signature line 
and the name associated with it. You can use as many < SIGNATURE _LINE> 
tags as you want within the context of the <SIGNATURE_list> tag. 
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MILSPEC Doctype Tag Reference 

<SIGNATURE^LIST> 


EXAMPLE The following example shows a sample use of the < SIGNATURE—LIST > tag. 

Note how it is used within the context of the global < TITLE-PAGE > tag. 

<FRONT_MATTER> 

<TITLE_PAGE> 


<SUBTITLE>(Submitted Under\Contract AOOOOO—11—A—2222) 
<SIGNATURE_LIST>(Authenticated by:\Approved by:) 
<SIGNATURE_LINE>(Procuring Activity\Program Manager) 
<SIGNATURE_LINE>(Date\Technical Director) 
<SIGNATURE_LINE>(\Consultant) 

<ENDSIGNATURE_LIST> 


<ENDTITLE_PAGE> 



MILSPEC Doctype Tag Reference 

<SPECIFICATION_INFO> 


<SPECIFICATION_INFO> 


Creates a listing of information about the specification on the title page 
and creates a two-line running heading for the rest of the document. 


FORMAT <SPECIFICATION_INFO > (specification-number 

\ code-id-number 
\ specification-date 
[ \ additional-info]) 


ARGUMENTS specification-number 

Specifies the number associated with this document. This number is 
formatted as the first line in a block of lines in the upper right of the title 
page. This number is also carried as the top line in a two-line running 
heading throughout the document. 

code-id-number 

Specifies the identification code number for this document. This number is 
formatted as the second line in a block of lines in the upper right of the title 
page. 

specification-date 

Specifies a date for the document. This value can be specified as a text string 
(for example, "31 October 1986"), or it can be specified using the global 
<DATE> tag, which produces the date at the time the file is processed. 

This date is formatted as the third line in a block of lines in the upper right 
of the title page; it is also carried as the bottom line in a two-line running 
heading throughout the document. 

additional-info 

Specifies additional information about the document (for example, "Part 1 of 
3 parts"). 

This information is formatted as the fourth line in a block of lines in the 
upper right of the title page. 


related tags • <signature_list> 

• < SIGNATURE _LINE> 

• < SPEC-TITLE > 

• <SUBTITLE> 

• The global <date> tag 

• The global <title_page> tag 

• The global <front_matter> tag 
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<SPECIFICATION_INFO> 


restrictions Valid only within the context of the global <TITLE_PAGE> tag. 


required None. 

terminator 


DESCRIPTION The < SPECIFICATION—INFO > tag creates a listing of information about the 

specification on the title page and creates a two-line running heading for the 
rest of the document. 

The listing of information is formatted on the upper right of the title page, 
each line specifies the following. 

• Line one lists the specification-number argument. 

• Line two lists the code-id-number argument. 

• Line three lists the specification-date argument. 

• Line four is optional and lists the additional-info argument. 

The specification-number and specification-date arguments are additionally 
used throughout the document as the top and bottom lines (respectively) of a 
two-line running heading. 


EXAMPLE The following example shows a sample use of the <specification_info> 

tag. 

<FRONT_MATTER> 

<TITLE_PAGE> 

<SPECIFICATI0N_INF0>(12345B\al42-b4\July 4. 1776\Part I of Three Parts) 

<SPEC_TITLE>(Prime Item Development Specification\ 

For the \(Approved Title)\of the \Supported\Device) 


<ENDTITLE_PAGE> 
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<SPEC_TITLE> 


<SPEC_TITLE> 

Creates a title with up to seven centered lines on the title page. 

FORMAT 

<SPEC_TITLE > (title-text- 1 [\ title-text-2 ... 

\ title-text-7]} 

ARGUMENTS 

title-text-n 

Specifies text within a title. Each argument is centered on a separate line on 
the title page. 

related tags 

• <SIGNATURE_LINE> 

• <SIGNATURE_LIST> 

• <SPECIFICATION_INFO> 

• < SUBTITLE > 

• The global <title_page> tag 

• The global <front_matter> tag 

restrictions 

Valid only within the context of the global <TITLE_PAGE> tag. 

required 

terminator 

None. 

DESCRIPTION 

Use the <SPEC_TITLE> tag to create the main title for a military specification. 
This title can have up to seven title lines; each is placed centered on the 
page beneath the previous title line. Use the <SUBTITLE> tag to create a 
subordinate title for a military specification. 

EXAMPLE 

The following example shows a sample use of the <spec_title> tag. 


<FRONT_MATTER> 

<TITLE_PAGE> 

<SPECIFICATI0N_INF0>(12345B\al42-b4\July 4. 1776\Part I of Three Parts) 
<SPEC_TITLE>(Prime Item Development Specification\ 

For the \(Approved Title)\of 
the \Device) 


<ENDTITLE_PAGE> 
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MILSPEC Doctype Tag Reference 

<SUBTITLE> 


<SUBTITLE> 

Creates a subtitle with up to seven centered lines on the title page. 

FORMAT 

<SUBTITLE> (title-text- 1 [\ title-text-2 . . . 

\ title-text-7]) 

ARGUMENTS 

title-text-n 

Specifies a text line within a subtitle. One to seven arguments can be 
specified. Each argument is centered on a separate subtitle line. 

related tags 

• <SIGNATURE_LIST> 

• <SIGNATURE_LINE> 

• <SPECIFICATION_INFO> 


• < SPEC-TITLE > 

• The global <title_page> tag 

• The global <front_matter> tag 

restrictions 

Valid only within the context of the global <title_page> tag. 

required 

terminator 

None. 

DESCRIPTION 

Use the < SUBTITLE > tag to create a subordinate title for a military 
specification. This subtitle can have up to seven title lines, each centered 
on the page beneath the previous title line. Use the <SPEC_TITLE> tag to 
create a main title for a military specification. 

EXAMPLE 

The following example shows a sample use of the < subtitle > tag. 


<FRONT_MATTER> 

<TITLE_PAGE> 

<SPECIFICATI0N_INF0>(12345B\al42-b4\July 4, 1776\Part I of Three Parts) 
<SPEC_TITLE>(Prime Item Development Specification\ 

For the \(Approved Title)\of the \Device) 

<SUBTITLE>(Submitted Under\Contract AOOOOO—11—A—2222) 
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1 2 OVERHEADS Doctype Tag Reference 


This chapter provides the reference information on all the tags available 
within the OVERHEADS doctype. Chapter 6 provides information on how to 
use these tags. 

The OVERHEADS doctype supports all of the VAX DOCUMENT global tags 
with the following exceptions: 

• <APPENDIX> 

• < CHAPTER > 

• <CONTENTS_FILE> 

• <FRONT_MATTER> 

• < GLOSSARY > 

• <HEAD1> through <HEAD6> 

• < INDEX-FILE > 

• <PART> 

• < PART-PAGE > 

• < PROFILE > 

See the VAX DOCUMENT User Manual, Volume 1 for more information on 
the global tags. 
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OVERHEADS Doctype Tag Reference 

<AUTHOR_INFO> 


<AUTHOR 

_INFO> 

Specifies informational text about the overhead slide presentation. 

FORMAT 

<AUTHOR_INFO> (info-line-1 [\ info-line-2] . . . 

[ \ info-line-4]} 

ARGUMENTS 

info-Une-n 

Specifies up to four lines of informational text. 

related tags 

• < INTRO-TITLE > 

• < INTRO-SUBTITLE > 

restrictions 

You can only use the <AUTHOR-lNFO> tag after the <SLIDE> tag in the 
SDML file. 

required 

terminator 

None. 


EXAMPLE The following example shows how to place a name, title, and date on a main 

title slide using the <author_info> tag. This text will be placed on the 
right side of the slide, toward the bottom of the page. 


<SLIDE> 

<INTRO_TITLE>(Advanced Development) 

<INTRO_SUBTITLE>(Status Report) 

<AUTH0R_INF0>(J.R. Drofnats\Technical Support\June 1986) 
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OVERHEADS Doctype Tag Reference 

<AUTO_NUMBER> 


<AUTO_NUMBER> 

Specifies that slides are to be numbered automatically, and that the slide 
number is to be placed at the bottom of every slide. Optionally, specifies 
text to be placed in front of the slide number. 

FORMAT 

<AUTO_NUMBER> [(text)] 

ARGUMENTS 

text 

Specifies text to be placed in front of the slide number at the foot of every 
overhead slide. If this argument is not specified, only the slide number is 
printed. 

related tags 

• < RUNNING-FEET > 

• <SLIDE> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

By default, no page or slide number is placed on the bottom of overhead 

slides. You can override this default behavior in the following ways: 

• Use the <AUTO_NUMBER> tag to request numbering and to optionally 
specify text to go along with the numbers. 

• Use the <running_feet> tag to specify text that is to be placed on the 
bottom of every overhead slide. 

• Use an argument to the <SLIDE> tag. The text of the tag's argument is 
placed on the bottom of the current slide. 

EXAMPLES 

In the following example the <auto_NUMBER> tag specifies that the slides 
are to be numbered. The current number will be placed in the bottom right 
corner of every slide. 


<AUTO_NUMBER> 


In the following example the <AUTO_NUMBER> tag specifies that the slides 
are to be numbered and that the numbers are to be preceded with the word 
"Earnings" and placed in the bottom right corner of every slide. 

2 <AUTO_NUMBER>(Earnings) 
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<INTRO_SUBTITLE> 


<INTRO_SUBTITLE> 

Creates a secondary title of up to four lines on an introductory slide. 

FORMAT 

<INTRO_SUBTITLE> (title-line-1 [\title-line-2] . . . 

[\ title-line-4]) 

ARGUMENTS 

title-line-n 

Specifies up to four lines of text for the secondary title. 

related tags 

• < INTRO-TITLE > 

• <SUBTITLE> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the <lNTRO_SUBTlTLE> tag to create a secondary title on the introductory 
presentation slide. The <INTR0_SUBTITLE> and <iNTRO_TiTLE> tags place a 
great deal of vertical space between their title lines. Note that, depending on 
the number of title lines you specify, the output of these tags may not leave 
room for any other text on the introductory slide. 

Use the < SUBTITLE > tag to create a subtitle of a slightly smaller type size 
and with less space between the title lines. 

EXAMPLE 

The following example illustrates an introductory title slide with a main title 
and a subtitle. Note that the title tags do not set text in uppercase by default. 


<SLIDE> 

<INTRO_TITLE>(LANGUAGES, TOOLS \ AND \DISPLAY SOFTWARE) 
<INTRO_SUBTITLE>(A PATH TO \PROGRAMMING PRODUCTIVITY) 


12-4 






OVERHEADS Doctype Tag Reference 

<INTRO_TITLE> 


<INTRO_TITLE> 

Creates a main title of up to four lines on an introductory slide. 

FORMAT 

<INTRO_TITLE> (title-line-1 [\ title-line-2] . . . 

[\ title-line-4]) 

ARGUMENTS 

title-line-n 

Specifies up to four lines of text for the title. 

related tags 

• < INTRO-SUBTITLE > 

• <SLIDE> 

• < TITLE > 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the <iNTRO_TiTLE> tag to create a main title on the introductory 
presentation slide. The <INTR0_TITLE> and <intro_SUBTITLE> tags place a 
great deal of vertical space between their title lines. Note that, depending on 
the number of title lines you specify, the output of these tags may not leave 
room for any other text on the introductory slide. 

Use the <title> tag to create a title of the same type size but with less 
space between the title lines. 

EXAMPLE 

The following example shows a slide with a two-line main introductory title. 


<SLIDE> 

<INTRO_TITLE>(Introduction to\The Management System) 
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OVERHEADS Doctype Tag Reference 

<RUNNING_FEET> 


<RUNNING 

_FEET> 

Specifies text to be placed at the bottom of the next slide and all 
subsequent slides. 

FORMAT 

<RUNNING_FEET> (running-footer-text) 

ARGUMENTS 

running-footer-text 

Specifies the text you want to be placed on your slides on the bottom left of 
the page. 

related tags 

• <AUTO_NUMBER> 

• < SLIDE > 

restrictions 

None. 

required 

terminator 

None. 


DESCRIPTION The <RUNNING_FEET> tag creates a running footer for a series of slides. This 

footer is output at the bottom left of the slide. If you want the tag to place 
running feet on all of your slides, you should place this tag in your SDML 
file before the first occurrence of a <SLIDE> tag. If you wish to disable these 
running feet, you should place the <RUNNING_FEET> tag in your SDML file 
with a null argument. 

By default, no page or slide number is placed on the bottom of overhead 
slides. You can override this default behavior in the following ways: 

• Use the <AUTO_NUMBER> tag to request numbering and to optionally 
specify text to go along with the numbers. 

• Use the <RUNNING_FEET> tag to specify text that is to be placed on the 
bottom of every overhead slide. 

• Use an argument to the <SLIDE> tag. The text of the tag's argument is 
placed on the bottom of the current slide. 

If <RUNNING_FEET> is specified in conjunction with <AUTO_NUMBER> , the 
slide number is placed on the right and the text on the left. 
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OVERHEADS Doctype Tag Reference 

<RUNNING_FEET> 


EXAMPLES In the following example, the <RUNNING_FEET> tag specifies that all slides 

are to carry the text "May 1986 Presentation" at the bottom right corner. 

Q <RUNNING^FEET>(May 1986 Presentation) 

<SLIDE> 

<TITLE>(Base Level 13) 

In the following example, the <auto_number> tag is used to create 
automatic numbering of the slides at the bottom right of the page, and 
the <RUNNING_FEET> tag is used to place a running footer on the bottom 
left of the page. 

g <RUNNING_FEET>(May 1987) 

<AUTO_NUMBER>(Slide) 
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OVERHEADS Doctype Tag Reference 

<RUNNING_TITLE> 


<RUNNING_TITLE> 


Creates a one- or two-line running heading at the top of each slide. 


FORMAT 


<RUNNIIMG_TITLE> (\ 


OFF 

title-1 [ \ title-2] 
[\FIRST_PAGE] 


\) 


ARGUMENTS title-1 

Specifies the text of a running title. If a two-line title is specified, this title is 
output on the upper title line. 

title-2 

Specifies the optional bottom line of a running title that has two lines. 

FIRST-PAGE 

Specifies that the running title is to begin output on the first slide. If this 
keyword is not specified, the running title begins on the slide after the current 
slide. 

OFF 

Specifies that any existing running titles created using the <RUNNING_TITLE> 
tag should be disabled for the slide on which this tag occurs and on any 
subsequent slides. 


related tags • <running_feet> 

• < SLIDE > 


restrictions None. 


required None. 

terminator 


DESCRIPTION Use the <RUNNING_TITLE> tag to create a one- or two-line running title for 

a series of slides. If you want the tag to place a running title on all of your 
slides, you should place this tag in your SDML file before the first occurrence 
of a < SLIDE > tag. If you use this tag within the context of the first < SLIDE > 
tag and you want the running title to begin on that slide, use the FIRST- 
PAGE argument. 

Use the OFF argument to disable any existing running titles created using the 
<RUNNING-TITLE > tag. These titles will then be disabled for the page on 
which this tag occurs and on any subsequent pages. 


12-8 







OVERHEADS Doctype Tag Reference 

<RUNNING_TITLE> 


Use the <RUNNING_FEET> tag to create a heading that appears at the bottom 
of the page. See the reference description of the <RUNNING_FEET> tag for 
more information on that tag. 


EXAMPLES The following examples show how to set running titles at the top of the page 

for a series of related slides. 

In the first example each occurrence of <running_title> creates a running 
title for the next slide or series of slides. 

Q <RUNNING_TITLE>(Introduction to SDML) 

<SLIDE> 

<TOPIC>(What is SDML?) 

<SLIDE> 

<TOPIC>(What is a Tag?) 

<RUNNING_TITLE>(Overview of the Tags) 

<SLIDE> 

<T0PIC>(The Basic Tags) 


The following example shows how you can disable a running title by using 
the OFF argument to the < RUNNING-TITLE > tag. 

<C0MMENT>(turn off running titles for the next slide) 

<RUNNING_TITLE>(OFF) 

<SLIDE> 

<T0PIC>(An Example of Output) 



OVERHEADS Doctype Tag Reference 

<SLIDE> 


<SLIDE> 

Begins a new overhead slide. 

FORMAT 

<SLIDE> ([footer-text]) 

ARGUMENTS 

footer-text 

Specifies text to be placed at the bottom of the slide. 

related tags 

• < RUNNING-TITLE > 


<AUTO_NUMBER> 

<RUNNING_FEET> 

<INTRO_TITLE> 

< INTRO-SUBTITLE > 

<AUTHOR_INFO> 

<TITLE> 

<SUBTITLE> 

<TOPIC> 

<TEXT_SIZE> 


restrictions None. 


required None. 

terminator 


DESCRIPTION The < SLIDE > tag begins a new overhead slide and generates a new page of 

output. An overhead slide can consist of the following; 

• Major titles and subtitles 

Use the <iNTRO_TiTLE> and <iNTRO_SUBTiTLE> tags to create title page 
slides. 

• Titles and subtitles followed by topics, lists, tables or text 

Use the <title> and <subtitle> tags to place headings at the top of 
each new slide. Use the global <LIST> (numbered) and <LIST> (unnumbered) 
tags for numbered and unnumbered lists. 

You can use any of the global tags to specify text elements on any slide 
page, except those associated with the creation of front matter, appendixes, 
glossaries, indexes, or part pages. 
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<SLIDE> 


EXAMPLES The following example shows a sequence of tags that begin a new slide and 

specify two main topics. 

Q <SLIDE> 

<TITLE>(System Components) 

<T0PIC>(Parser) 

<T0PIC>(Interpreter) 

In the following example a slide is specified with a main heading and a 
subheading. The text "Slide 1 " will be placed at the bottom of this slide. 

g <SLIDE>(Slide 1) 

<INTRO_TITLE>(A New \ Production System) 

<INTRO_SUBTITLE>(Introduction and Overview) 

The following example shows a slide that uses a numbered list to number 
steps. 

E] <SLIDE> 

<TITLE>(WORK FLOW) 

<LIST>(NUMBERED) 

<LE>Create the File 
<LE>Run the Checker 
<ENDLIST> 
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<SUBTITLE> 


<SUBTITLE> 

Specifies a secondary title for a new slide. 

FORMAT 

<SUBTITLE> (title-line-1 [\ title-line-2] . . . 

[\ title-line-4]) 

ARGUMENTS 

title-line-n 

Specifies up to four lines of text for the secondary slide title. 

related tags 

• < TITLE > 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the <SUBTITLE> tag to create a subordinate title for an overhead slide 
that has up to four separate lines. Each of the subtitle lines is centered on 
the output page. Use the <title> tag to create a main title for an overhead 
slide. 

EXAMPLE 

The following example illustrates an overhead slide that begins with a main 
title followed by a subtitle. 


<SLIDE> 

<TITLE>(FILE PROCESSING) 

<SUBTITLE>(CONCEPTS AND INSTRUCTIONS) 
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<TEXT_SIZE> 


<TEXT_SIZE> 


Changes the size of type used within the context of topics, tables, and 
lists on a single slide. 


FORMAT 


<TEXT_SIZE> { 


SMALL 

REGULAR 

TABLE 


) 


ARGUMENTS SMALL 

Reduces the standard point size of type used in topics and lists. 

REGULAR 

Increases the size of type in tables to that of standard text. 

TABLE 

Reduces text to the smallest font size available in the OVERHEADS doctype, 
which is the standard font size used inside of tables. 


related tags • <slide> 


restrictions None. 


required <endtext_size> 

terminator 


DESCRIPTION Use the <TEXT_SIZE> tag to change the size of type in a single overhead 

slide. This tag alters the type face used by text in the following contexts: 

• Text specified within a list using the global <LIST> tag 

• Text specified as an argument to the <TOPlC> tag 

• Text specified within the context of the global < TABLE > tag 

The <TEXT_SIZE> tag alters the default size of type only on a single slide. 
The following slide will have the default type sizes. To alter the type size for 
more than one slide, use the <text_size> tag on each of the slides. 
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<TEXT_SIZE> 


EXAMPLE 


The following example illustrates each of the various formats available using 
the <TEXT_siZE> tag. 


<SLIDE> 

<T0PIC>(ANIMALS THAT MAKE GOOD PETS) 

<list>(UNNUMBERED) 

<LE>Rabbits—Small, furry, generally best as pets for children 
growing up in a non-urban setting. 

<p><TEXT_SIZE>(small) 

Rabbits are typically not good pets in urban settings because of their 
extreme sensitivity to noise and because of their love of the outdoors. 
<ENDTEXT_SIZE> 

<LE>Dogs—Come in assorted shapes and sizes: a general purpose pet. 
<p><TEXT_SIZE>(TABLE) 

Dogs are man’s (and woman’s) best friend. 

<ENDTEXT_SIZE> 

<LE>Cats—Cats are ideal pets for apartment dwellers. 

<p> 

<TEXT_SIZE>(regular) 

Cats should not be pets in households that already have tropical fish for pets. 
<ENDTEXT_SIZE> 

<ENDLIST> 
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<TITLE> 


<TITLE> 

Specifies a title for a new slide. 

FORMAT 

<TITLE> (title-line-1 [\ title-line-2] . . . [ \ title-line-4]) 

ARGUMENTS 

title-line-n 

Specifies up to four lines of text for a main slide title. 

related tags 

• < SUBTITLE > 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the <TITLE> tag to create a main title for an overhead slide that has up 
to four separate lines. Each of the title lines is centered on the slide. Use the 
<SUBTITLE> tag to create a subordinate title for an overhead slide. 

EXAMPLES 

The following example shows a sequence of tags that begin a new slide and 
specifies a single-line title. 


g <SLIDE> 

<TITLE>(System Components) 

<T0PIC>(Parser) 

<T0PIC>(Interpreter) 

This example illustrates a three-line title. Each line is centered. 

2 <TITLE>(THE \DEVELOPMENT \CYCLE) 
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<TOPIC> 


<TOPIC> 

Specifies a line of topic text for a slide. 

FORMAT 

<TOPIC> (topic-text) 

ARGUMENTS 

topic-text 

Specifies text for the topic. 

related tags 

• < SLIDE > 

• <TEXT_SIZE> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the <TOPlC> tag to specify a topic line for a slide. The text of the 
<TOPiC> tag begins at the left margin and has a smaller type font than the 
font used by the < title > tag. You can alter the size of the topic text by 
using the <TEXT_SIZE> tag. 

EXAMPLE 

The following example illustrates a slide with a title, a topic sentence and an 
unnumbered list. 


<SLIDE> 

<TITLE>(THE \DEVELOPMENT \CYCLE) 
<T0PIC>(WH0) 

<LIST>(UNNUMBERED) 

<LE>WRITERS 

<LE>EDITORS 

<LE>C0MP0SIT0RS AND ARTISTS 
<ENDLIST> 
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1 3 REPORT Doctype Tag Reference 


This chapter contains the reference information on the doctype-specific tags 
available within the REPORT doctype. Chapter 7 provides information on 
how to use these tags. 

The REPORT doctype accepts the full range of VAX DOCUMENT global tags, 
See the VAX DOCUMENT User Manual, Volume 1 for more information on 
the global tags. The REPORT doctype also provides tags that let you do the 
following: 

• Create headings or modify the default attributes of the REPORT doctype 

• Create signature lines and list author information within the context of 
the global <front_matter> tag 

• Create formal outlines within the context of the < outline > tag 
These tags are described alphabetically in this chapter. 
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REPORT Doctype Tag Reference 
<AUTHOR> 


<AUTHOR> 

Places the name of an author and one or two additional lines of information 
about the author in the front matter portion of a document. 

FORMAT 

<AUTHOR> (author-name [\ author-info-1] 

[ \ author-info-2]) 

ARGUMENTS 

author-name 

Specifies the name of the author. 

author-info-n 

Specifies any additional information about the author below the author's 
name. Information specified as author-info-1 is placed above information 
specified as author-irifo-2. 

related tags 

• < BYLINE > 

• <SIGNATURES> 

• The global <FRONT_MATTER> tag 

restrictions 

Valid only in the context of the global <FRONT_MATTER> tag in the REPORT 
doctype. 

required 

terminator 

None. 

DESCRIPTION 

Use the <author> tag to place the name of an author in the front matter of 
a document. This tag accepts two optional arguments to provide additional 
information about the author. 

If you want a signatory line for the author in the front matter, use the 
<SIGNATURES> and <BYLINE> tags. See the descriptions of those tags in 
this chapter for more information. 
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REPORT Doctype Tag Reference 

<AUTHOR> 


EXAMPLE The following example shows how you can use the <AUTHOR> tag within 

the front matter of a document. Note how the optional second argument to 
the <AUTHOR> tag is used to list the author's title. 

<FRONT_MATTER> 

<TITLE_PAGE> 

<TITLE>(The NYUC Simulator Reference Manual) 

<ORDER_NUMBER>(AA-ZOOOO-TE) 

<ABSTRACT> 

This manual describes the NYUC Simulator. 

This program simulates a conversation between three people 
by analyzing the syntactic and semantic components of three 
related statements, and then synthesizing statements and responses 
based upon these original statements. 

<ENDABSTRACT> 

<REVISION_INFO>(This revision is personally signed.) 

<AUTH0R>(Mr. Jones\Research Head, STG Inc.) 

<SIGNATURES> 

<BYLINE>(Nat Jones\Author) 

<DATE>(July 11, 1985) 

<PRINT_DATE>(June 1987) 

<ENDTITLE_PAGE> 

<ENDFRONT_MATTER> 
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<BYLINE> 


<BYLINE> 

Places a name and other optional information below a ruled line in a 
signature list. 

FORMAT 

<BYLINE> (name [ \ additional-info]) 

ARGUMENTS 

name 

Specifies the name of the signatory. This name is placed under the beginning 
of the signature line on the left side of the page. 

additional-info 

Specifies any additional information about the signatory. This information is 
placed on the same line as the name argument with an em dash (—) between 
the two arguments. 

related tags 

• <AUTHOR> 

• <SIGNATURES> 

• The global <front_matter> tag 

restrictions 

Valid only in the context of the global <front_matter> tag after the 
<SIGNATURES> tag. 

required 

terminator 

None. 

DESCRIPTION 

Use the < byline > tag to create an approval line in the front matter of a 
document and to place the name of a signatory beneath that line. You can 
place additional information about the signer by using the additional-info 
argument. Additional information is formatted to the right of the name of the 
signer, on the same line, separated by an em dash ( — ). 

You can use as many < byline > tags as you want to create approval lines 
within the front matter of a document, as long as all of these tags follow 
the <SIGNATURES> tag. You can use the <SIGNATURES> tag to begin all the 
approval lines on a separate page of the front matter. See the < SIGNATURES > 
tag in this chapter for more information. 
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REPORT Doctype Tag Reference 

<BYLINE> 


EXAMPLE The following example shows three occurrences of the < BYLINE > tag. The 

first two occurrences list the positions of the signers using the optional 
additional-info argument. The third occurrence of the <BYLINE> tag omits 
the optional argument. Note that all three tags follow the <SIGNATURES> 
tag. 

<FRONT_MATTER> 

<TITLE_PAGE> 

<TITLE>(The NYUC Simulator Reference Manual) 

<REVISI0N_INF0>(This revision is personally signed.) 

<AUTHOR>(Mr. Jones\Research Head. STG Inc.) 

<SIGNATURES> 

<BYLINE>(Nat Jones\Author) 

<BYLINE>(Cecil Mills\Co-author) 

<BYLINE>(Matt Smith) 

<DATE>(July 11, 1985) 

<PRINT_DATE>(June 1987) 

<ENDTITLE_PAGE> 

<ENDFRONT_MATTER> 
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<CHEAD> 


<CHEAD> 

Creates a centered heading. 

FORMAT 

<CHEAD> (heading-text [\ symbol-name]) 

ARGUMENTS 

heading-text 

Specifies the text of the centered heading. 

symbol-name 

Specifies a symbol to identify the heading associated with the <CHEAD> tag. 
You can use this argument if you are planning to reference this heading by its 
title elsewhere in the document. This argument is provided so that you can 
reference unnumbered headings. 

The symbol-name argument can be any text string of 31 characters or less 
without spaces. This text must contain only the letters A through Z, the 
numbers 0 through 9 and the underscore (_) character. The symbol-name 
may not begin with an underscore character. 

related tags 

• <HEAD> 

• < SECTION > 

• The global <center> tag 

• The global <headi> tag 

• The global <REFERENCE> tag 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <CHEAD> tag places a secondary, unnumbered heading on the center 
of the output page. The capitalization of the heading is kept as you enter it. 

If you need to use a primary unnumbered heading, use the <HEAD> or the 
<SECTION> tags. 
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<CHEAD> 


EXAMPLE The following example shows how to use the <chead> and <head> 

tags to create unnumbered headings. Note that the <chead> tag uses the 
optional symbol-name argument so that it can be referred to in the previous 
section using the global < reference > tag. 

<HEAD>(How to Write a Letter) 

<P> 

The first thing that you should do in writing a letter is to get 
a clean piece of paper and a well-sharpened pencil. 

<REFERENCE>(paper_getting) describes how to procure a piece of paper. 

<CHEAD>(Getting the Piece of Paper\paper_getting) 

<P> 

You can buy clean paper in most major supermarkets, department stores, 
and hardware stores. You should try to get ruled paper so that 
your letter will be neat and easy to read. 
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<COLUMN> 


<COLUMN> 

Specifies that a new column of output should begin in a two-column 
doctype. 

FORMAT 

<COLUMN> 

ARGUMENTS 

None. 

related tags 

• The global <final_cleanup> tag 

restrictions 

Valid only in a two-column doctype such as REPORT.TWOCOL or ARTICLE. 

required 

terminator 

None. 

DESCRIPTION 

Use the < column > tag to cause the text immediately following it to be 
started in a new column. If this tag occurs in the left text column, the text 
immediately following it begins in the right text column. If this tag occurs 
in the right text column, the text immediately following it begins in the left 
column of the next page. 

Use the <COLUMN> tag when you always want to begin a new column at 
that point in your text. You can use the COLUMN—BREAK argument to the 
global < FINAL-CLEANUP > tag to also specify a column break; however, this 
should be used only during the final processing of the two-column document. 

See Section 2.2 for more information on improving the formatting of a 
two-column doctype such as REPORT.TWOCOL. 

EXAMPLE 

The following example shows how to use the < column > tag to begin a new 
text column. In this example, the writer wants the two descriptions to appear 
side by side, one in each column. 
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REPORT Doctype Tag Reference 

<COLUMN> 


<CHEAD>(Woodwind Instruments) 

<P>Woodwind instruments have the following 
attributes; 

<LIST>(UNNUMBERED) 

<LE>They are often made of wood, hence their name. 

<LE>Musicians create sound using these instruments by causing a reed 
to vibrate. 


<ENDLIST> 

<C0LUMN> 

<CHEAD>(Brass Instruments) 

<P>Brass instruments have the following 
attributes: 

<LIST>(UNNUMBERED) 

<LE>They are often made of brass, hence their name. 
<LE>Musicians create sound using these instruments by 
vibrating (buzzing) their lips into a steel mouthpiece. 


<ENDLIST> 



REPORT Doctype Tag Reference 

<DOCUI\/IENT_ATTRIBUTES> 


<DOCUMENT_ATTRIBUTES> 

Enables doctype-specific tags that override the default design format of 
the REPORT doctype. 

FORMAT 

<DOCUMENT_ATTRIBUTES> 

ARGUMENTS 

None. 

related tags 

None. 

restrictions 

None. 

required 

terminator 

< ENDDOCUMENT-ATTRIBUTES > 

DESCRIPTION 

The <DOCUMENT-ATTRlBUTES> tag can be used in three doctypes: 


• ARTICLE 

• REPORT 

• SOFTWARE 


The < DOCUMENT-ATTRIBUTES > tag enables a group of tags in each of these 
doctypes that allow you to modify the default format of that doctype. These 
tags are recognized only within the context of the < DOCUMENT-ATTRIBUTES > 
tag. If other VAX DOCUMENT tags occur in this context, they are ignored, as 
if they had occurred within the context of a <COMMENT> tag. 

Typically, you use the < DOCUMENT-ATTRIBUTES > tag at the beginning of an 
input file (or in a file specified using the DOCUMENT /INCLUDE qualifier) 
to alter the default format of a doctype for the processing of that entire file. 

Table 13-1 summarizes the formatting tags enabled by the <document_ 
ATTRIBUTES > tag in each of the three supported doctypes. 
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<DOCUMENT_ATTRIBUTES> 


Table 13-1 Doctype-specific Tags Enabled by the <document_attributes> tag 

Formatting Tags Description 

Tags Enabled in the ARTICLE Doctype 

<SET_HEADINGS> (UNNUMBERED) The <SET_HEADINGS> tag specifies whether 

<SET_HEADINGS> (NUMBERED) numbered or unnumbered headings are produced 

by the heading-level tags ( <HEAD1> , <HEAD2> , 
and so on). By default, headings are not numbered 
in a document processed using the ARTICLE 
doctype. 

Use the <SET_HEADINGS> (NUMBERED) tag to 
specify that your headings should be numbered. 


Tags Enabled in the REPORT Doctype 

<SET_PAGE_NUMBERING> (BY_CHAPTER) 
<SET_PAGE_NUMBERING> (SEQUENTIAL) 


<SET_FORMAL_ELEMENT_NUMBERING> (BY_CHAPTER) 
<SET_FORMAL_ELEMENT_NUMBERING> (SEQUENTIAL) 


The <SET_PAGE_NUMBERING> tag specifies 
how pages are to be numbered in a document 
processed using the REPORT doctype. Pages are 
numbered sequentially by default. 

If the BY_CHAPTER argument is used, the pages 
are numbered by chapter. For example, the second 
page in Chapter 3 would be numbered 3-2. If the 
BY_CHAPTER argument is used in a document 
that contains no chapters, the page numbering is 
sequential. 

The SEQUENTIAL argument specifies that the 
pages should be numbered sequentially, as they 
are by default. 

The <SET_FORMAL_ELEMENT_NUMBERING> tag 
specifies how formal tables, figures, and examples 
are to be numbered in a document processed using 
the REPORT doctype. By default, formal tables, 
figures, and examples are numbered sequentially. 

The BY_CHAPTER argument indicates that formal 
elements are to be numbered using the chapter 
prefix; for example, the first formal table in 
Chapter 4 would be numbered as Table 4-1. 

The SEQUENTIAL argument indicates that 
formal elements are to be numbered sequentially 
throughout the document; for example, the eighth 
formal table in the document, regardless of what 
chapter it occurs in, would be numbered as 
Table 8. 

If the BY_CHAPTER argument is used in 
a document that contains no chapters, 

VAX DOCUMENT uses the default sequential 
formal element numbering. 
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REPORT Doctype Tag Reference 

<DOCUMENT_ATTRIBUTES> 


Table 13-1 (Cent.) Doctype-specific Tags Enabled by the <document_attributes> tag 


Formatting Tags 

Description 

Tags Enabled in the SOFTWARE Doctype 


<SET-RUNNING_TITLES> (BY-HEADONE) 

The <SET-RUNNING-TITLES> tag specifies 
that the running title at the top of each page is 
composed of two lines: the first line is the title 
of the chapter, and the second line is the heading 
text of the current <HEAD1> tag. Note that the 
argument BY_HEADONE is required. 

By default, the chapter title is used as a single-line 
running title. 


EXAMPLE The following example is of a file that is to be processed under the REPORT 

doctype. This example shows how the <SET_PAGE_NUMBERING> and <SET_ 
FORMAL-ELEMENT-NUMBERING > tags can be used to create page and formal 
element numbering that is chapter-oriented rather than sequential. Note how 
the BY—CHAPTER argument is used by both tags to specify that numbering 
should be by chapter rather than sequential. 

<DOCUMENT_ATTRIBUTES> 

<SET_PAGE_NUMBERING>(BY.CHAPTER) 

<SET_FORMAL_ELEMENT_NUMBERING>(BY_CHAPTER) 

<ENDDOCUMENT_ATTRIBUTES> 
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<HEAD> 

<HEAD> 

Places a main heading on the left of the page. 

FORMAT 

<HEAD> (heading-text [ \ symbol-name]) 

ARGUMENTS 

heading-text 

Specifies the text of the heading. 

symbol-name 

Specifies the symbol to identify the heading associated with the <HEAD> 
tag. Use this argument if you are planning to reference this heading by its 
title elsewhere in the document. This argument is provided so that you can 
reference unnumbered headings. 

The symbol-name argument can be any text string of 31 characters or less 
without spaces. This text must contain only the letters A through Z, the 
numbers 0 through 9 and the underscore ( —) character. The symbol-name 
may not begin with an underscore character. 

related tags 

• <CHEAD> 

• < SECTION > 

• The global <HEAD1> tag 

• The global <reference> tag 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <HEAD> tag is one of three unnumbered heading tags available only 
in the REPORT doctype. This tag places an unnumbered heading on the 
left-hand side of the output page. 

The other REPORT doctype-specific tags that produce unnumbered headings 
are the <section> and the <chead> tags. See the appropriate reference 
descriptions in this chapter for more information on these tags. 

You may also want to use the global <SUBHEAD1> and <SUBHEAD2> 
tags to produce unnumbered headings in the REPORT doctype. See the 

VAX DOCUMENT User Manual, Volume 1 for more information on these tags. 
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<HEAD> 


EXAMPLE The following example shows how to use the <HEAD> and <CHEAD> 

tags to create unnumbered headings. Note that the <HEAD> tag uses the 
optional symbol-name argument so that it can be referred to in the previous 
section using the <reference> tag. 

<CHEAD>(How to Write a Letter) 

<P> 

The first thing that you should do in writing a letter is to get 
a clean piece of paper and a well-sharpened pencil. 

<REFERENCE>(paper_getting) describes how to procure a piece of paper. 

<HEAD>(Getting the Piece of Paper\paper_getting) 

<P> 

You can buy clean paper in most major supermarkets, department stores, 
and hardware stores. You should try to get ruled paper so that 
your letter will be neat and easy to read. 


13-14 




REPORT Doctype Tag Reference 

<LEVEL> 


<LEVEL> 

Specifies an outline entry and the organizational level of that outline entry. 

FORMAT 

<LEVEL> (level-number \ entry-text) 

ARGUMENTS 

level-number 

Specifies the organizational level of the entry. This argument can be any 
whole number from 1 to 6. 

entry-text 

Specifies the text for a particular level. 

related tags 

• < OUTLINE > 

• <SHOW_LEVELS> 

restrictions 

Valid only in the context of the < OUTLINE > tag. 

required 

terminator 

None. 

DESCRIPTION 

The <LEVEL> tag is used to create numbered entries in an outline. Top-level 
entries (those specified as <LEVEL> (l)) are marked using uppercase Roman 
numerals. At the lowest level, level 6, the entries are marked with lowercase 
letters enclosed in parentheses. The top level is formatted at the current left 
margin; each lower level is indented from the level above it. 


EXAMPLE The following example illustrates an outline created using the < LEVEL > 

tag in the context of the <OUTLlNE> tag. Note how the <LEVEL> tags 
are indented in the SDML file to make the file easier to read and more 
maintainable. 

<OUTLINE>(<EMPHASIS>(Maxillary Taxonomy)\An Enumeration of the 
Maxillae\from a Dentition Perspective) 

<LEVEL>(l\Historical introduction) 

<LEVEL>(l\Dentition in various groups of vertebrates) 

<LEVEL>(2\Reptilia) 

<LEVEL>(3\Histology and development of reptile teeth) 

<LEVEL>(4\Survey of forms) 
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<OUTUNE> 


<OUTLINE> 

Begins an outline and specifies a title for the outline. 

FORMAT 

<OUTLINE> [( title-line-1 [\ title-line-2] 

[\ title-line-3]}] 

ARGUMENTS 

title-line-n 

Specifies a title line. Up to three title lines can be specified. 

related tags 

• <LEVEL> 

• <SHOW_LEVELS> 

restrictions 

None. 

required 

terminator 

<ENDOUTLINE> 


DESCRIPTION The <OUTLlNE> tag begins an outline and defines the <LEVEL> and 

< SHOW-LEVELS > tags. You can use the < outline > tag only within the 
REPORT doctype. 


An outline is a hierarchical list of numbered elements in which the hierarchy 
is conveyed to the reader through the letter or number on each outline entry 
and the indentation level. The < OUTLINE > tag begins an outline that permits 
up to six levels in the hierarchy. At the top level, level 1, the outline entries 
are marked with uppercase Roman numerals. At the lowest level, level 6, 
the outline entries are marked with lowercase letters enclosed in parentheses. 
The top level is formatted at the current left margin; each lower level is 
indented from the level above it. 

If one or more title lines are supplied as arguments to the < outline > tag, 
the lines are centered above the outline. You may want to add emphasis to 
some or all of the title lines. 

The outline usually is aligned at the left margin of the text, but it can be 
embedded in other tags, for example after an <LE> tag, in which case it 
is aligned with other list elements. Likewise, other tags can be embedded 
within the outline, so that text or sublists can be interspersed with the outline 
entries. 

An outline does not affect heading levels that are established with any of 
the heading tags ( <HEADl> , <HEAD2> , and so on). Outline entries do not 
appear in the table of contents. 
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<OUTLINE> 


EXAMPLE The following example illustrates an outline created using the < OUTLINE > 

tag and the tags it enables. Note how the <LEVEL> tags are indented in 
the SDML file to make the file easier to read and more maintainable. This 
indentation in the SDML file has no effect on the output, which is indented 
automatically according to the level specified in the <LEVEL> tags. 

<OUTLINE>(<EMPHASIS>(Maxillary Taxonomy)\An Enumeration of the 
MaxillaeXfrom a Dentition Perspective) 

<LEVEL>(l\Historical introduction) 

<LEVEL>(i\Dentition in various groups of vertebrates) 

<LEVEL>(2\Reptilia) 

<LEVEL>(3\Histology and development of reptile teeth) 

<LEVEL>(4\Survey of forms) 

<LEVEL>(2\Mammalia) 

<LEVEL>(3\Histology and development of mammalian teeth) 

<LEVEL>(3\Survey of forms) 

<LEVEL>(4\Primates) 

<LEVEL>(5\Lemuroidea) 

<LEVEL>(5\Anthropoidea) 

<LEVEL>(6\Platyrrhini) 

<LEVEL>(6\Catarrhini) 

<LEVEL>(4\Carnivora) 

<LEVEL>(5\Creodonta) 

<LEVEL>(5\Fissipedia) 

<LEVEL>(6\Aeluroidea) 

<LEVEL>(6\Arctoidea) 

<LEVEL>(5\Pinnipedia) 

<LEVEL>(4\Etc<hellipsis>) 

<ENDOUTLINE> 
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<RUNNING_FEET> 


<RUNNING 

i_FEET> 

Creates a single line heading at the bottom of each page. 

FORMAT 

<RUNNING_FEET> (title-text) 

ARGUMENTS 

title-text 

Specifies the text to be used as a running heading at the foot of the page. 

related tags 

• < RUNNING-TITLE > 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the <running_feet> tag to place a heading at the bottom of every 
page. This heading is called a "footer" because it appears at the foot of 
the page. When the same footer is used for several pages, the footers are 
collectively called "running feet," 

This tag accepts one argument, which is the text that should appear at the 
bottom of the page. This text is output exactly as entered, including spacing 
and capitalization. 

Use the <RUNNING_TITLE> tag to create a heading at the top of the page. 

See the < RUNNING-TITLE > tag in this chapter for more information. 

Note that the headings established by the <RUNNING-FEET> and 
<RUNNING-TITLE> tags may be overriden by a subsequent use of the 
<CHAPTER> tag. 

EXAMPLE 

The following example shows how to use the <runninG-FEET> tag to place 
the heading "Getting the Piece of Paper" at the bottom of each page. The 
running footer will be output exactly as entered. 


<RUNNING_FEET>(Getting the Piece of Paper) 

<CHEAD>(Getting the Piece of Paper) 

<p> 

You cam buy clean paper in most major supermarkets, department stores, 
and hardware stores. You should try to get ruled paper so that 
your letter will be neat and easy to read. 
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<RUNNING_TITLE> 


<RUNNING^TITLE> 


Creates a one- or two-line running heading at the top of each page. 


FORMAT 


<RUNNIIMG_TITLE> { \ 


OFF 

title-1 [\ title-2] 
[\FIRST_PAGE] 



ARGUMENTS title-1 

Specifies the text of a running title. If a two-line title is specified, this title is 
output on the upper title line. 

title-2 

Specifies the bottom line of a running title that has two lines. 

FIRST-PAGE 

Specifies that the running title is to be placed on the first output page. If 
this keyword is not specified, the running title is placed on the page after the 
current page. 

OFF 

Specifies that any existing running titles created using the <RUNNING_TITLE> 
tag should be disabled for the page on which this tag occurs and on any 
subsequent pages. 


related tags • <running_feet> 


restrictions None. 


required None. 

terminator 


DESCRIPTION Use the <running_title> tag to specify a one- or two-line title at the top 

of the page. Use the FIRST-PAGE argument to the <running_TITLE> tag to 
begin the title lines on the first page of output, rather than on the page after 
the current page as is the default. 

Use the OFF argument to disable any existing running titles created using the 
<RUNNING_TITLE> tag. These titles will then be disabled for the page on 
which this tag occurs and on any subsequent pages. 

Use the < RUNNING _FEET> tag to create a heading that appears at the 
bottom of the page. See the <RUNNING_FEET> tag in this chapter for more 
information. 
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<RUNNING_TITLE> 


The headings established by the <running_title> and <RUNNING_FEET> 
tags may be overridden by a subsequent use of the <chapter> tag. 


EXAMPLES The following examples show how to use the <running_title> tag to 

create titles and how to disable them. 

The following example shows how to use the <running_title> tag to 
create the two-line running title "An E. B. Bartz Course:" "Writing Quality 
Correspondence." Note that because the FIRST-PAGE argument is used, the 
^ two-line running title will appear at the top of the first page. 

Q <RUNNING_TITLE>(An E. B. Bartz Course:\Writiag Quality Correspondence\FIRST_PAGE) 

<HEAD>(How to Write a Letter) 

<P> 

The first thing that you should do in writing a letter is to get 
a clean piece of paper and a well-sharpened pencil. 

The following example shows how you can disable a running title by using 
the OFF argument to the < RUNNING-TITLE > tag. 

2 <C0MMENT>(turn off running titles for the following example page) 

<RUNNING_TITLE>(OFF) 

<HEAD>(An Example of a Letter) 
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<SECTION> 


<SECTION> 

Begins a new page and creates a major heading on the left side of that 
page. 

FORMAT 

<SECTION> (heading-text [\ symbol-name]) 

ARGUMENTS 

heading-text 

Specifies the text of the section heading. 

symbol-name 

Specifies a symbol to identify the heading created by the < SECTION > tag. 

Use this argument if you are planning to reference this heading by its title 
elsewhere in the document. This argument is provided so that you can 
reference unnumbered headings. 

The symbol-name argument can be any text string of 31 characters or less 
without spaces. This text must contain only the letters A through Z, the 
numbers 0 through 9 and the underscore (_) character. The symbol-name 
may not begin with an underscore character. 

related tags 

• <CHEAD> 

• <HEAD> 

• The global <CHAPTER> tag 

• The global <HEADl> tag 

• The global < REFERENCE > tag 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <SECTlON> tag is one of the three REPORT doctype-specific tags that 
create unnumbered headings. The <SECTlON> tag begins a new output page 
and creates a major heading on the left-hand side of that page. The other tags 
in the REPORT doctype that produce unnumbered headings are the <HEAD> 
and the <chead> tags; these tags do not begin a new page of output. 
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<SECTION> 


EXAMPLE The following example shows how to use the < SECTION > tag to begin a new 

page and place an unnumbered heading on that page. Note that this sample 
omits the symbol-name argument to the <section> tag, because the writer 
will not be referencing this section. 

<SECTI0N>(Writing Personal Correspondence) 

<P> 

Writing personal correspondence is more fun and less formal than 
writing business correspondence, but much of the same rules apply. 

<HEAD>(How to Write a Letter) 

<P> 

The first thing that you should do in writing a letter is to get 
a clean piece of paper and a well-sharpened pencil. 
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<SHOW_LEVELS> 



DESCRIPTION The <SHOW_LEVELS> tag lets you emphasize the text associated with one 

or more <LEVEL> tags. Such text is output in a bold typeface if the BOLD 
argument is used, or in an italic typeface if the ITALIC argument is used. 

The OFF argument disables the bolding or italicizing of the text used as an 
argument to the <LEVEL> tag. If the <show_levels> tag is not used, or if 
it is specified with the OFF argument, the standard typeface is used within 
the outline. 

See the <LEVEL> tag description in this chapter for more information on the 
<LEVEL> tag. 
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<SHOW_LEVELS> 


EXAMPLE The following example shows an outline that uses the <SHOW_levels> tag. 

The entry text is italicized using the <SHOW_LEVELS> (ITALIC) tag beginning 
with the second-level entry "Mammalia" through the fourth-level entry 
"Primates." The italicized text is then turned off using the OFF argument to 
the <SHOW_LEVELS> tag. 

<0UTLINE>(<EMPHASIS>(Maxillary Taxonomy)\An Enumeration of the 
MaxillaeXfrom a Dentition Perspective) 

<LEVEL>(l\Hi8torical introduction) 

<LEVEL>(l\Dentition in various groups of vertebrates) 

<LEVEL>(2\Reptilia) 

<LEVEL>(3\Histology and development of reptile teeth) 

<LEVEL>(4\Survey of forms) 

<COMMENT>(**ltalicize the information covered on this weeks test**) 

<SHOW_LEVELS>(ITALIC) 

<LEVEL>(2\Mammalia) 

<LEVEL>(3\Histology and development of mammalian teeth) 

<LEVEL>(3\Survey of forms) 

<LEVEL>(4\Primates) 

<COMMENT>(**tiurn off italicization**) 

<SHOW_LEVELS>(OFF) 

<LEVEL>(5\Lemuroidea) 

<LEVEL>(5\Anthropoidea) 

<LEVEL>(6\Platyrrhini) 

<LEVEL>(6\Catarrhini) 

<LEVEL>(4\Carnivora) 

<LEVEL>(5\Creodonta) 

<LEVEL>(5\Fissipedia) 

<LEVEL>(6\Aeluroidea) 

<LEVEL>(6\Arctoidea) 

<LEVEL>(5\Pinnipedia) 

<LEVEL>(4\Etc<hellipsis>) 

<END0UTL1NE> 
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<SIGNATURES> 


<SIGNATURES> 

Begins a list of signatures which are to appear in the front matter of a 
document. 

FORMAT 

<SIGNATURES> [(NEWPAGE}] 

ARGUMENTS 

NEWPAGE 

Specifies that the signature list is to begin on a new page. 

related tags 

• <AUTHOR> 

• < BYLINE > 

• The global < FRONT-MATTER > tag 

restrictions 

Valid only when following the global <FRONT_MATTER> tag in the REPORT 
doctype. 

required 

terminator 

None. 

DESCRIPTION 

The < SIGNATURES > tag begins a list of persons who are to sign a document. 
Each person's name is listed by using the < BYLINE > tag following the 
<SIGNATURES> tag. The <BYLINE> tag places the name of the person, and 
additional information about that person (such as their title or affiliation), 
below a line on which the person is to sign. 

See the reference description of the < byline > tag for more information on 
that tag. ' 

EXAMPLE 

The following example shows the < SIGNATURES > tag beginning a list of 
signature lines. Note how the < byline > tag is used to create each signature 
line. 


<FRONT_MATTER> 

<TITLE_PAGE> 

<TITLE>(The NYUC Simulator Reference Manual) 
<REVISION_INFO>(This revision is personally signed.) 
<AUTH0R>(Mr. Jones\Research Head, STG^Inc.) 
<SIGNATURES> 

<BYLINE>(Nat Jones\Author) 

<BYLINE>(Cecil Mills\Co-author) 

<ENDTITLE_PAGE> 

<ENDFRONT_MATTER> 
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^4 SOFTWARE DoctypeTag Reference 


This chapter provides reference information on the SOFTWARE doctype tags 
and templates. Chapter 8 provides the tutorial information on these tags and 
templates. 

This reference chapter divides the SOFTWARE doctype tags into the following 
groups: 

• Tags that can be used anywhere in the SOFTWARE doctype, including 
inside or outside of the reference templates. 

• Tags available in any of the reference templates. 

• Tags available only in the Command template. 

• Tags available only in the Routine template. 

• Tags available only in the Statement template. 

• Tags available only in the Tag template. 

The program examples in this chapter were processed using a local doctype 
based on one of the six SOFTWARE doctypes. Your output of these examples 
may vary depending on the doctype you processed the example under, and 
whether any doctype modifications have been made to your local installation 
of VAX DOCUMENT. Each output example is introduced by a form of the 
sentence, "This example may produce the following output," to remind you 
that the output examples may vary. 


14.1 The SOFTWARE Doctype Tags 

The tags described in this section are available for use anywhere in a 
SOFTWARE doctype. 
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<ARGDEFLIST> 


<ARGDEFLIST> 

Begins a definition list of arguments. 


FORMAT alternate-heading 

<ARGDEFLIST> [( NOHEAD 

. NONE 


ARGUMENTS alternate-heading 

Specifies a heading to override the current default text heading. The default 
heading provided by VAX DOCUMENT for the <ARGDEFLIST> tag can 
vary. See the description section for more information on default argument 
definition list headings. 

NOHEAD 

Suppresses the output of the default heading for the <ARGDEFLIST> tag. 

NONE 

Causes the text "None." to be written to indicate that no arguments are 
available. Note that when using the NONE keyword the <endargdeflist> 
tag should not be used. 

related tags • <argitem> 

• <ARGTEXT> 

• <ARGDEF> 

• <PARAMDEFLIST> 

• <QUALDEFLIST> 

• <SET_TEMPLATE_HEADING> 

• The global <DEFiNiTiON_LiST> tag 

required <endargdeflist> 

terminator Required unless the NONE keyword is specified as an argument to the 

<ARGDEFLIST> tag. 

restrictions None. 


DESCRIPTION The <ARGDEFLIST> tag creates a definition list of arguments; it is similar 

in format and syntax to the global <DEFlNlTlON_LiST> tag. See the 
VAX DOCUMENT User Manual, Volume 1 for more information on the 
<DEFINITION_LIST> tag. 
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<ARGDEFLIST> 


The <ARGDEFLIST> tag enables two tags to create an argument definition list. 
The <ARGITEM> tag labels the list item being defined, and the <argdef> 
tag begins the definition of the list item. 

When the <ARGDEFLIST> tag is used within the Routine template, 
the arguments accepted by the <ARGITEM> tag are changed, and the 
<ARGTEXT> tag is enabled. The change in the arguments accepted by 
the <ARGITEM> tag and the addition of the <ARGTEXT> tag give you a 
more structured environment in which to create Routine template argument 
definition lists. See the descriptions of these tags in this chapter for more 
information. 

When the <argdeflist> tag is used within the templates, a default heading 
is provided. This heading can be modified for that single argument definition 
list using the alternate-heading argument. A heading specified in this way 
overrides any existing default heading. 

Use the <set_template-Heading > tag to create your own default headings 
within a reference template. Using this tag modifies the default headings 
for all subsequent <ARGDEFLIST> tags used in that reference template. See 
the reference description of the <SET_TEMPLATE_HEADING> tag for more 
information on that tag. 

When the <ARGDEFLIST> tag is used outside of a template, no default 
heading is defined for it. You can create your own heading for a single 
argument definition list by specifying that heading as the alternate-heading 
argument. 

The default headings for the <ARGDEFLIST> are listed by their context in the 
following informal table. 


Context 

Default Heading 

Command Template 

"Arguments" 

Routine Template 

"Arguments " 

Tag Template 

"Arguments" 

Statement Template 

No default heading 

Outside of a Template 

No default heading 


EXAMPLES The following examples show various uses of the <ARGDEFLIST> tag. The 

first example shows an argument definition list used outside of the context 
of the Routine template. Note the syntax used for the <argitem> tag. The 
second example shows two argument definition lists used within the routine 
template. 

Q <ARGDEFLIST>(Arguments) 

<ARGITEM>(data-l\data-2) 

<ARGDEF>Specifies the arguments through which data is passed to the routine. 

<ENDARGDEFLIST> 

This example may produce the following output. 
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<ARGDEFLIST> 


ARGUMENTS data-1 

data-2 

Specifies the arguments through which data is passed to the routine. 

The following example shows two argument definition lists used within the 
Routine template. The first list is coded using the Routine template-specific 
<ARGITEM> tag syntax. Note the headings produced by the <argitem> tag 
in the output of this example. 

The second argument definition list illustrates a use of the <ARGTEXT> 
tag. Typically, the <ARGTEXT> tag is used instead of the <ARG1TEM> or 
<ARGDEF> tags. 

0 <ROUTINE_SECTION> 


<ARGDEFLIST> 

<ARGITEM>(x\floating_point\F_Floating,D_Floating, G_Floating, or H_Floating 
\read onlyXby referenceXmay also be passed by value) 

<ARGDEF>The number for which the square root is desired. 

<ENDARGDEFLIST> 

<ARGDEFLIST> 

<ARGTEXT> 

The arguments to the SYS$N0NE routine are identical to those used 

by the SYS$NULL routine. See the description of the SYS$NULL routine for 

more information on these arguments. 

<ENDARGTEXT> 

<ENDARGDEFLIST> 


<ENDROUTINE_SECTION> 


This example may produce the following output. 


ARGUMENTS 


X 

VMS Usage: floating-point 

type: F_Floating,D_Floating, G—Floating, or H—Floating 

access: read only 

mechanism: by reference—may also be passed by value 

The number for which the square root is desired. 


ARGUMENTS The arguments to the SYS$NONE routine are identical to those used by the 

SYS$NULL routine. See the description of the SYS$NULL routine for more 
information on these arguments. 
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<ARGDEF> 


<ARGDEF> 

Begins the text that defines an item in an argument definition list. 

FORMAT 

<ARGDEF> 

ARGUMENTS 

None. 

related tags 

• <ARGDEFLIST> 

• <ARGITEM> 

restrictions 

May only be used in the context of the <ARGDEFLIST> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <ARGDEF> tag is used within an argument definition list to label the 
beginning of the text that defines a list item. This text describes the item 
listed by the previous <ARGITEM> tag. The text begun by the <argdef> 
tag is terminated by the next <ARGITEM> or <ENDARGDEFLIST> tag. 

EXAMPLE 

<ARGDEFLIST>(Arguments) 
<ARGITEM>(data-l\data-2) 

The following example shows an argument definition list used outside of the 
routine template. 

<ARGDEF>Specifies the arguments through which data is passed to the routine. 

<ENDARGDEFLIST> 

This example may produce the following output. 

ARGUMENTS 

data-1 
data-2 

Specifies the arguments through which data is passed to the routine. 
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<ARGITEM> 


<ARGITEM> 


Labels one to seven routine argument items to be defined in an argument 
definition list outside of the Routine template, or a single routine argument 
and its attributes within the Routine template. 


FORMAT <ARGITEM> (item-1 [\ item-2 . . . \ item-7]) 

<ARGITEM> (arg-name[ \ usage-information 
\data-type \ access 
\ mechanism] \ mechanism-info]]) 


ARGUMENTS item-n 

Specifies the item in the argument list to be defined. This tag accepts a 
minimum of one item-n argument and a maximum of seven. When more 
than one item-n argument is specified, each subsequent item-n argument after 
the initial argument is formatted under the first argument. 

arg-name 

Specifies the descriptive name assigned to the argument for reference 
purposes. 

usage-information 

Specifies a keyword indicating the category of data to which the argument's 
value belongs. These keywords are system dependent, and are specified by 
agreed-upon conventions. 

data-type 

Specifies the data type of the argument, for example, longword, byte, G_ 
floating, and so on. 

access 

Specifies the access applied to the argument; for example, read-only, write- 
only, and so on. 

mechanism 

Specifies the mechanism by which the argument is passed; for example, by 
descriptor, by reference, or by value. 

mechanism-info 

Specifies additional information that may be appended to the mechanism 
argument output. 


related tags 


• <ARGDEF> 

• <ARGTEXT> 

• <ARGDEFLIST> 
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<ARGITEM> 


restrictions 


required 

terminator 


DESCRIPTION 


EXAMPLE 


The first syntax listed in the format section is valid within an argument 
definition list outside of the Routine template. The second syntax listed in the 
format section is valid only within an argument definition list inside of the 
Routine template. 


<ARGDEF> 


The <ARGITEM> tag labels items in an argument definition list within the 
context of the <argdeflist> tag; however, it accepts one of two sets of 
arguments, depending on whether or not the <ARGITEM> tag is used within 
the Routine reference template. 

If the <ARGITEM> tag is used outside of the Routine template, it accepts the 
item-n argument, which may be repeated up to seven times, as specified in 
the first syntax listed in the Format section. This form of the <ARGITEM> 
tag allows you to label one to seven routine argument items inside of an 
argument definition list. 

If the <ARGITEM> tag is used within the Routine template, it uses the 
arguments listed in the second syntax listed in the Format section. This form 
of the <ARGITEM> tag allows you to label a single routine argument and its 
attributes. 


See the example in the <ARGDEFLIST> tag description. 
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<ARGUMENT> 


<ARGUMENT> 

Emphasizes an argument name within text. 

FORMAT 

<ARGUMENT> (argument-name) 

ARGUMENTS 

argument-name 

Specifies an argument name to be emphasized. 

related tags 

• < VARIABLE > 

• < KEYWORD > 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <ARGUMENT> tag causes the argument-name to appear in an altered font 
(such as boldface or italics). This tag does not alter the case of its argument. 

EXAMPLE 

The following example shows a sample use of the <ARGUMENT> tag. 


<p> 

The <ARGUMENT>(newadr) argument to the $ADJSTK function 
provides the address of a longword to receive the updated value. 

This example may produce the following output. 

The newadr argument to the $ADJSTK function provides the address of a 
longword to receive the updated value. 
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<AUTHOR> 


<AUTHOR> 

Places the name of an author and one or two additional lines of information 
about the author in the front matter portion of a document processed 
using the SOFTWARE.SPECIFICATION doctype. 

FORMAT 

< AUTHOR> (author-name [ \ author-info-1 ] 

[ \ author-info-2]) 

ARGUMENTS 

author-name 

Specifies the name of the author. If the author-info-n arguments are used, this 
line will be the top line. 

author-info-n 

Specifies any additional information on the author. Information specified as 
author-info-1 is placed above information specified as author-info-2 

related tags 

• < BYLINE > 

• <SIGNATURES> 

• The global <front_matter> tag 

restrictions 

Available only in the SOFTWARE.SPECIFICATION doctype following the 
global <FRONT_MATTER> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <AUTHOR> tag lets you place the name of an author in the front matter 
of a document. This tag accepts two optional arguments to provide additional 
information about the author. 

If you want a signatory line for the author in the front matter, use the 
<SIGNATURES> and <BYLINE> tags. See the reference descriptions of those 
tags in this chapter for more information. 
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<AUTHOR> 


EXAMPLE The following example shows how you can use the <author> tag within 

the front matter of a document. Note how the optional second argument to 
the <AUTHOR> tag is used to list the position of the author. 

<FRONT_MATTER> 

<TITLE_PAGE> 

<TITLE>(The NYUC Simulator Reference Manual) 

<ORDER_NUMBER>(AA-ZOOOO-TE) 

<ABSTRACT> 

This manual describes the NYUC Simulator. 

This program simulates a conversation between three people 
by analyzing the syntactic and semantic components of three 
related statements, and then synthesizing statements and responses 
based upon these original statements. 

<ENDABSTRACT> 

<REVISION_INFO>(This revision is personally signed.) 

<AUTH0R>(Mr. Jones\Research Head, STG Inc.) 

<SIGNATURES> 

<BYLINE>(Nat JonesXAuthor) 

<DATE>(July 11, 1985) 

<PRINT_DATE>(June 1987) 

<ENDTITLE_PAGE> 

<ENDFRONT_MATTER> 


14-10 





SOFTWARE Doctype Tag Reference 

<BYLINE> 

<BYLINE> 

Places a name and other optional information below a ruled line in a 
signature list processed using the SOFTWARE.SPECIFICATION doctype. 

FORMAT 

<BYLINE> (name [\ additional-info]) 

ARGUMENTS 

name 

Specifies the name of the signatory. This name is placed under the beginning 
of the signature line on the left side of the page. 

additional-info 

Specifies any additional information about the signatory. This information is 
placed on the same line as the name argument with an em dash (—) between 
the two arguments. 

related tags 

• <AUTHOR> 

• < SIGNATURES > 

• The global <front_matter> tag 

restrictions 

Available only in the context of the < SIGNATURES > tag. 

required 

terminator 

None. 

DESCRIPTION 

The < BYLINE > tag lets you create an approval line in the front matter of 
a document and place the name of the signatory beneath that line. You 
can optionally place additional information about the signer by using the 
additional-info argument. Additional information is formatted to the right of 
the name of the signer, on the same line, separated by an em dash ( — ). 


You can use as many < byline > tags as you want to create approval lines 
within the front matter of a document, as long as all of these tags follow 
the <SIGNATURES> tag. You can use the <signatures> tag to begin all 
the approval lines on a separate page of the front matter. See the reference 
description of the < SIGNATURES > tag in this section for more information on 
that tag. 
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<BYLINE> 


EXAMPLE The following example shows three occurrences of the < BYLINE > tag. The 

first two occurrences list the positions of the signers using the optional 
additional-info argument; the third occurrence omits the optional argument. 
Note that all three tags follow the <SIGNATURES> tag. 

<FRONT_MATTER> 

<TITLE_PAGE> 

<TITLE>(The NYUC Simulator Reference Manual) 

<REVISION_INFO>(This revision is personally signed.) 

<AUTH0R>(Mr. Jones\Research Head, STG Inc.) 

<SIGNATURES> 

<BYLINE>(Nat Jones\Author) 

<BYLINE>(Cecil Mills\Co-author) 

<BYLINE>(Matt Smith) 

<DATE>(July 11. 1985) 

<PRINT_DATE>(June 1987) 

<ENDTITLE_PAGE> 

<ENDFRONT_MATTER> 
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<CPOS> 


<CPOS> 

Marks the cursor position in a screen display. 

FORMAT 

<CPOS> (placement'Character) 

ARGUMENTS 

placement-character 

Specifies the character occupying the position of the cursor. This character 
can be a blank space. 

related tags 

• <DISPLAY> 

• <KEY> 

• <KEY_SEQUENCE> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <CPOS> tag places a special character within a screen display to indicate 
the position of the cursor. 

EXAMPLE 

The following example shows how to use the <CPOS> tag to indicate a 
cursor's position. In this case the cursor is placed on the letter X in the 
directory specification [TRXTFILES]. 


<p> 

To correct the file specification, move the 

cursor to the incorrect letter as shown in the following example: 
<DISPLAY> 

$ COPY ABC.TXT [TR<CPOS>(X)TFILES] 

<ENDDISPLAY> 


This example may produce the following output. 

To correct the file specification, move the cursor to the incorrect letter as 
shown in the following example: 

$ COPY ABC.TXT [TRXTFILES] 
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<DELETE_KEY> 


<DELETE- 

.KEY> 

Creates a special character resembling a DELETE key on a keyboard. 

FORMAT 

<DELETE_KEY> 

ARGUMENTS 

None. 

related tags 

• <GRAPHIC> 

• <KEY> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The < DELETE-KEY > tag creates a special character that represents the delete 
key used on many types of keyboards. 

EXAMPLE 

The following example shows how you can use the <DELETE_KEY> tag to 
create the delete key symbol. 


<p> 

You press the DELETE key (<DELETE_KEY>) to delete the text. 

This example may produce the following output. 

You press the DELETE key (<x] ) to delete the text. 
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<DISPLAY> 



ARGUMENTS display-text 

Specifies a display fragment you want to insert into your text. If this 
argument is not specified, the <ENDDISPLAY> tag is required. 

KEEP 

Specifies that the display example should be placed on the next page rather 
than breaking it between the current page and the next page. If the display 
example is longer than a single page, it will be broken between the current 
page and the next page. 

WIDE 

Indicates a wide display that may exceed the normal right margin of the text. 

MAXIMUM 

Indicates that the example may require additional adjustment to fit within the 
bounds of the text page. May be used only with the WIDE keyword. Using 
this argument may result in the display text being output in a smaller type 
face. 

related tags • <syntax> 

• The global < interactive > tag 

• The global <VALID_BREAK> tag 

restrictions You cannot use tab characters, index tags (such as <x> and <Y> ), text 

element tags (such as <P> , <LIST> , or <note> ), or the <math> tag 
within any example. 

required <enddisplay> 

terminator Required if the display example is not passed as the display-text argument. 
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<DISPLAY> 


DESCRIPTION Use the <DISPLAY> tag to create display examples either as fragments in 

text or as extended examples. Such display examples are distinguished 
typographically from the surrounding text upon output. 

If you want to place a display fragment in the text of your document, specify 
the display-text argument as the only argument to the <DISPLAY> tag and do 
not specify the <enddisplay> tag. This format is shown first in the format 
section of the <display> tag. 

If you have a long display example that you want to appear distinctly separate 
from the text of your document, place the text for the example between the 
<DISPLAY> and <ENDDISPLAY> tags. This format is shown second in the 
format section of the < DISPLAY > tag. 

Display examples specified in this way retain all spaces and line breaks as 
entered. This allows you to position the text in the example so that it appears 
similar to a terminal screen display. When you specify display examples in 
this form, you can use the KEEP, WIDE, and MAXIMUM keyword arguments 
to control the formatting of your example. 

If you have an especially long display example, you may want to use the 
< VALID-BREAK > tag in your example to indicate where a page may break. 


EXAMPLES The following examples show how to use the < DISPLAY > tag. 

The first example shows a display example that uses the < DISPLAY > and 
<ENDDISPLAY> tags. Note the use of the KEEP keyword to ensure that the 
display example is not broken across the page. 

Q <P>The operating system indicates success with the following 
message: 

<DISPLAY>(KEEP) 

Welcome to VAX/VMS Version 4.4 

Username: 

<ENDDISPLAY> 

This example may produce the following output. 

The operating system indicates success with the following message: 

Welcome to VAX/VMS Version 4.4 


Username: 

The following example shows the <display> tag used to create a display 
fragment in text. Note that the <enddisplay> tag is omitted and that no 
keywords to the <display> tag can be specified. 

<P>The message <DISPLAY>(Welcome to VAX/VMS Version 4.4) 
is issued by default when a user presses RETURN. 

This example may produce the following output. 

The message Welcome to VAX/VMS Version 4.4 is issued by default when a 
user presses RETURN. 
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<DOCUMENT_ATTRIBUTES> 


<DOCUMENT_ATTRIBUTES> 


Enables doctype-specific tags that override the default design format of 
the SOFTWARE doctype. 

FORMAT 

<DOCUMENT_ATTRIBUTES> 

ARGUMENTS 

None. 

related tags 

None. 

restrictions 

None. 

required 

terminator 

< ENDDOCUMENT-ATTRIBUTES > 

DESCRIPTION 

The < DOCUMENT-ATTRIBUTES > tag can be used in three doctypes: 


• ARTICLE 

• REPORT 

• SOFTWARE 


The <DOCUMENT_ATTRlBUTES> tag enables a group of tags in each of these 
doctypes that allow you to modify the default format of that doctype. These 
tags are recognized only within the context of the <document_attributes> 
tag. If other VAX DOCUMENT tags occur in this context, they are ignored 
just as if they had occurred within the context of a <COMMENT> tag. 

Typically, you use the < DOCUMENT-ATTRIBUTES > tag at the beginning of an 
input file (or in a file specified using the DOCUMENT /INCLUDE qualifier) 
to alter the default format of a doctype for the processing of that entire file. 

Table 14-1 summarizes the formatting tags enabled by the < DOCUMENT- 
ATTRIBUTES > tag in each of the three supported doctypes. 
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Table 14-1 Doctype-specific Tags Enabled by the <document_attributes> tag 

Formatting Tags Description 

Tags Enabled in the ARTICLE Doctype 

<SET_HEADINGS> (UNNUMBERED) The <SET_HEADINGS> tag specifies whether 

<SET_HEADINGS> (NUMBERED) numbered or unnumbered headings are produced 

by the heading-level tags ( <HEAD1> , <HEAD2> , 
and so on). By default, headings are not numbered 
in a document processed using the ARTICLE 
doctype. 

Use the <SET_HEADINGS> (NUMBERED) tag to 
specify that your headings should be numbered. 


Tags Enabled in the REPORT Doctype 

<SET_PAGE_NUMBERING> (BY_CHAPTER) 
<SET_PAGE_NUMBERING> (SEQUENTIAL) 


<SET_FORMAL_ELEMENT_NUMBERING> (BY_CHAPTER) 
<SET_FORMAL_ELEMENT_NUMBERING> (SEQUENTIAL) 


The <SET_PAGE_NUMBERING> tag specifies 
how pages are to be numbered in a document 
processed using the REPORT doctype. Pages are 
numbered sequentially by default. 

If the BY_CHAPTER argument is used, the pages 
are numbered by chapter. For example, the second 
page in Chapter 3 would be numbered 3-2. If the 
BY_CHAPTER argument is used in a document 
that contains no chapters, the page numbering is 
sequential. 

The SEQUENTIAL argument specifies that the 
pages should be numbered sequentially, as they 
are by default. 

The <SET_FORMAL_ELEMENT_NUMBERING> tag 
specifies how formal tables, figures, and examples 
are to be numbered in a document processed using 
the REPORT doctype. By default, formal tables, 
figures, and examples are numbered sequentially. 

The BY_CHAPTER argument indicates that formal 
elements are to be numbered using the chapter 
prefix; for example, the first formal table in 
Chapter 4 would be numbered as Table 4-1. 

The SEQUENTIAL argument indicates that 
formal elements are to be numbered sequentially 
throughout the document; for example, the eighth 
formal table in the document, regardless of what 
chapter it occurs in, would be numbered as 
Table 8. 

If the BY_CHAPTER argument is used in 
a document that contains no chapters, 

VAX DOCUMENT uses the default sequential 
formal element numbering. 
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<DOCUMENT_ATTRIBUTES> 


Table 14-1 (Cent.) Doctype-specific Tags Enabled by the <document_attributes> tag 


Formatting Tags 

Description 

Tags Enabled in the SOFTWARE Doctype 

<SET_RUNNING_TITLES> (BY_HEADONE) 

The <SET_RUNNING_TITLES> tag specifies 
that the running title at the top of each page is 
composed of two lines: the first line is the title 
of the chapter, and the second line is the heading 
text of the current <HEAD1> tag. Note that the 
argument BY_HEADONE is required. 

By default, the chapter title is used as a single-line 
running title. 



EXAMPLE The following example of a file processed under the SOFTWARE doctype 

shows how a two-line running title is specified using the <SET_RUNNING_ 
TITLES> tag. This title will have the title of the current chapter as the first 
line, and the heading text of the current <HEADl> tag as the second line. 

<DOCUMENT_ATTRIBUTES> 

<SET_RUNNING_TITLES>(BY.HEADONE) 

<ENDDOCUMENT_ATTRIBUTES> 
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< EXAMPLE_SEQUENCE> 

Begins a numbered sequence of informal examples. 

FORMAT 

< EXAMPLE_SEQUENCE> [([heading-info] 

[\ NONUMBER]}] 

ARGUMENTS 

heading-info 

Consists of one of the following arguments: 

• EXAMPLE—Causes the singular heading "Example" to be output. Also 
suppresses numbering of the example. Use this argument when you 
supply only one example. 

• Heading-text—Causes the specified text to be used as a heading rather 
than the default heading "Examples." 

• NOHEAD—Suppresses the output of a heading for the section. 

NONUMBER 

Suppresses numbering of the examples. When EXAMPLE is supplied as the 

first argument, the NONUMBER argument is unnecessary. 

related tags 

• <EXAMPLES_INTRO> 

• <EXC> 

• <EXI> 

• < EXTEXT > 

restrictions 

None. 

required 

terminator 

< ENDEX AMPLE -SEQUENCE > 

DESCRIPTION 

The <EXAMPLE-SEQUENCE> tag begins a sequence of informal numbered 
examples. This tag (and the tags it enables to create the examples) can be 
used inside or outside of the reference templates. 


Even though the examples are numbered, they are generally not referred to 
by these numbers. Instead, explanatory text directly follows each example. 
The example sections in this chapter provide examples of output from the 
< EXAMPLE-SEQUENCE > tag. 

By contrast, the global < example > tag begins a formal example that is 
usually located within a chapter or section that is not formatted by a template. 
A formal example receives a number and caption, is listed in the table of 
contents, and can be referred to in a cross-reference. 
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<EXAMPLE_SEQUENCE> 


Following the <example_sequence> tag, each example begins with either 
the <EXC> or <EXI> tags. Use the <EXC> tag to present code examples; 
use the <EXI> tag to present interactive examples. Use the <EXTEXT> tag to 
terminate an example begun using the <EXI> or <EXC> tags and to begin 
the text that explains the example. 

For some doctypes the <EXC> and <EXI> tags can use the full page width, 
which causes the example to begin on the far left of the page. The < extext> 
tag, however, causes the text to be left justified at the normal text margin. 


EXAMPLE The following example shows two short interactive examples, a code example, 

and their explanatory text. The <S> and <U> tags are used to label the 
system and user portions of the interaction. 


<examplG_sequence>(Debugging Examples) 

<exi><s>(DBG> )<u>(SCROLL/LEFT) 

<extext>This command scrolls the screen left by eight spaces or columns. 
<exi><s>(DBG> )<u>(SCROLL/UP:4) 

<extext>This command scrolls 4 lines up through the display. 

<exc>PSL: CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV TN Z V C 
0 0 0 0 USER USER 0 00 10000 

!Display formatted the PSL. 
!A11 bits are cleared. 

<extext> 

This shows you the contents of the PSL after issuing the EXAMINE command. 
<endexample_sequence> 

This example may produce the following output: 


DEBUGGING 

EXAMPLES 

Q DBG> SCROLL/LEFT 

This command scrolls the screen left by eight spaces or columns. 

@ DBG> SCROLL/UP:4 

This command scrolls 4 lines up through the display. 

K] PSL: CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV TN Z V C 
0 0 0 0 USER USER 0 00 1 0000 

!Display formatted the PSL. 

!A11 bits are cleared. 

This shows you the contents of the PSL after issuing the EXAMINE 
command. 
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<EXAMPLES_INTRO> 


< EX AM PLES_I NTRO > 

Provides introductory text before an example. 

FORMAT 

<EXAMPLES_INTRO> 

ARGUMENTS 

None. 

related tags 

• < EXAMPLE-SEQUENCE > 

• <EXC> 

• <EXI> 

• <EXTEXT> 

restrictions 

Available only in the context of the <EXAMPLE_SEQUENCE> tag. 

required 

terminator 

None. 

DESCRIPTION 

Use the <examples_intro> tag to provide an introduction to numbered 
examples. 


EXAMPLE The following example shows introductory text to two interactive examples 

and their explanatory text. 


<EXAMPLE_SEQUENCE>(Debugging Examples) 

<EXAMPLES_ INTRO 

The following examples show various uses of the DBG Utility; 

<EXI><S>(DBG>)<U>(SCROLL/LEFT) 

<EXTEXT> 

This command scrolls the screen left by eight spaces or columns. 

<EXI><S>(DBG>)<U>(SCROLL/UP:4) 

<EXTEXT> 

This command scrolls 4 lines up through the display. 

<ENDEXAMPLE_SEQUENCE> 

This example may produce the following output: 
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< EXAM PLES_I NTRO> 


DEBUGGING 

EXAMPLES 

Q DBOSCROLL/LEFT 
0 DBG>SCR0LL/UP:4 


The following examples show various uses of the DBG Utility: 


This command scrolls the screen left by eight spaces or columns. 


This command scrolls 4 lines up through the display. 
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<EXC> 

Begins a code example within a series of numbered informal examples. 

FORMAT 

<EXC> 

ARGUMENTS 

None. 

related tags 

• <EXAMPLE_SEQUENCE> 

• <EXAMPLES_INTRO> 

• <EXI> 

• <EXTEXT> 

• The global < CODE-EXAMPLE > tag 

restrictions 

• Valid only in the context of the < EXAMPLE-SEQUENCE > tag. 

• The first line of the code example must be on the same source file line as 
the <EXC> tag. 

• Indexing tags such as <x> and <Y> tags are invalid within the context 
of the code example. 

required 

terminator 

<EXTEXT> 

DESCRIPTION 

The <EXC> tag begins a code example within a series of numbered examples. 
The text following the <EXC> tag is treated as the text of the code example 
until that example is terminated by the <extext> tag. 

The <EXC> and <extext> tags can be used much like the global <CODE_ 
EXAMPLE > and <ENDCODE-EXAMPLE > tags, with the exception that when 
using the <EXC> tag to begin a code example, the first line of the code 
example text must be on the same source file line as the <EXC> tag. This 
ensures that the code example is formatted correctly on the page. 


EXAMPLE 

See the example in the discussion of the <example_sequence> tag. 
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<EXI> 


<EXI> 

Begins an interactive example within a series of numbered informal 
examples. 

FORMAT 

<EXI> 

ARGUMENTS 

None. 

related tags 

• <EXAMPLE_SEQUENCE> 


<EXC> 


<EXTEXT> 

The global < interactive > tag 
The global <S> tag 
The global <u> tag 


restrictions 

• Valid only in the context of the < EXAMPLE-SEQUENCE > tag. 

• The first line of the interactive example must be on the same source file 
line as the <EXi> tag. 

required 

terminator 

<EXTEXT> 

DESCRIPTION 

The <EXI> tag begins an interactive example within a series of numbered 
examples. The text following the <EXI> tag is taken as the text of the 
interactive example until that example is terminated by the < EXTEXT > tag. 
Use the global <u> and <S> tags within the context of the <EXI> tag in 
the same way they are used within the context of the global < INTERACTIVE > 
tag. 

The <EXi> and <extext> tags can be used just like the <interactive> 
and <endinteractive> tags, with the exception that when using the <EXi> 
tag to begin an interactive example, the first line of the interactive example 
text must be on the same source file line as the <EXI> tag. This ensures that 
the interactive example is formatted correctly on the page. 
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<EXI> 


EXAMPLE The following example shows a use of the <EXI> tag within the context of 

the <EXAMPLE_SEQUENCE> tag to begin an interactive example. To produce 
a space between the DCL prompt and the user-entered command, you should 
include the space within the argument to the <S> tag. 

<EXAMPLE_SEQUENCE>(DCL Examples) 

<EXI><S>($ )<U>(SH0W TIME) 

<S>(16-APR-1984 15:18:44) 

<EXTEXT>Thi8 example shows how to use the DCL command SHOW TIME to 
request a display of the date and time. 

<ENDEXAMPLE_SEqUENCE> 


This example may produce the following output. 


DCL 

EXAMPLES 

Q $ SHOW TIME 

16-APR-1984 15:18:44 


This example shows how to use the DCL command SHOW TIME to request 
a display of the date and time. 
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<EXTEXT> 

Terminates an example and begins an explanation in a sequence of 
numbered examples. 

FORMAT 

<EXTEXT> 

ARGUMENTS 

None. 

related tags 

• <EXAMPLE_SEQUENCE> 

• <EXAMPLES_INTRO> 

• <EXI> 

• <EXC> 

restrictions 

Can be used only in the context of an < EXAMPLE-SEQUENCE > tag. 

required 

terminator 

None. 

DESCRIPTION 

The <EXTEXT> tag terminates a code example or an interactive example, 
and begins an explanation of the previous example. Within an <EXAMPLE_ 
SEQUENCE> tag section, each numbered example begins with either the 
<EXC> or <EXI> tag, depending on whether you want a code example 
or an interactive example. Both kinds of examples are terminated by the 
< EXTEXT > tag, which labels the beginning of the text that explains the 
previous example. 

Use the <EXAMPLES_intro> tag to place explanatory text before the first 
example in the example sequence. See the description of the <EXAMPLES_ 
INTRO> tag for more information. 


EXAMPLE 

See the example in the discussions of the <example_SEQUENCE> and <EXI> tags. 
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<GRAPHIC> 

Displays terminal graphics characters. 

FORMAT 

<GRAPHIC> ^char-7 \ char-2} 

ARGUMENTS 

char-1 

Specifies the character to be used as the top portion of the graphics character. 

char-2 

Specifies the character to be used as the bottom portion of the graphics 
character. 

related tags 

• <KEY> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The <GRAPHIC> tag creates a single graphics terminal character (such as the 
linefeed or formfeed characters) by combining the two characters you specify 
as arguments. The second character you specify appears lower and adjacent 
to the first character. 

EXAMPLE 

The following example shows how you can use the <GRAPHIC> tag to create 
the linefeed and formfeed characters that can appear on a computer terminal. 


<p> 

The <GRAPHIC>(F\F) and the <GRAPHIC>(L\F) 
are two characters that the terminal displays. 

This example may produce the following output. 

The and the Ij, are two characters that the terminal displays. 
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DESCRIPTION The <KEY> tag labels the keys of a keyboard or keypad. If you are using 

the <KEY> in conjunction with the <KEY-SEQUENCE> tag, you can specify a 
second label that this tag stacks under the first. 

The optional keyword arguments BOX and TEXT determine how the key 
labels appear in your document. If you specify BOX (the default), this tag 
draws a box around the labels. If you specify TEXT, this tag encloses the 
labels in angle brackets. 
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<KEY> 


EXAMPLE In the following example, note that in the context of the <key_sequence> 

tag, the <KEY> tag accepts two key-lahel-n arguments. Outside of the context 
of the <KEY_SEQUENCE> tag, it accepts only a single key-lahel-n argument. 

Note also that the first <KEY> tag is specified with no keyword argument. 
This tag uses the default keyword argument BOX. The second <KEY> tag 
includes the BOX keyword argument to specify BOX formatting. The third 
<KEY> tag includes the TEXT keyword argument. 


<p> 

You would use the following sequence of keys: 

<KEY_SEqUENCE> 

<KEY>(Next\Screen) <KEY_PLUS> <KEY>(PF3\B0X) 

<ENDKEY_SEqUENCE> 

<P> 

These keys are not associated with the <KEY>(WHITE\TEXT) keys. 


This example may produce the following output. 
You would use the following sequence of keys; 


Next 

Screen 


+ [M 


These keys are not associated with the < WHITE > keys. 





SOFTWARE Doctype Tag Reference 

<KEY_NAME> 


<KEY_NAME> 

Emphasizes the name of a key within text. 

FORMAT 

<KEY-_NAME> (key-name) 

ARGUMENTS 

key-name 

Specifies the name of the key. This often corresponds to the name on a key 
label. 

related tags 

• <CPOS> 

• <KEY> 

• <KEY_SEQUENCE> 

• <GRAPHIC> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

The < KEY-NAME > tag alters the appearance of a key name within text using 
uppercase letters, boldface, or italics. 

EXAMPLE 

<P> 

In the following example the < KEY-NAME > tag alters the appearance of the 
GOLD key. 


In EDT, the <KEY_NAME>(GOLD) key changes the function of the other keys 
on the keypad. 


This example may produce the following output: 

In EDT, the GOLD key changes the function of the other keys on the keypad. 
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<KEYPAD> 

Specifies an individual keypad diagram and optionally supplies a title for 
that diagram. 

FORMAT 

< KEYPAD > i 3lternate-heading[\ DISPLAY] \ n 

^ 1 DISPLAY 1 

ARGUMENTS 

heading-text 

Specifies the text of a heading for a keypad diagram. By default, this tag 
produces no heading. 

DISPLAY 

Allows you to specify individual key labels as arguments to the tags 
<KEYPAD_ROW> and <KEYPAD_ENDROW> . 

related tags 

• <KEYPAD_ENDROW> 

• <KEYPAD_ROW> 

• <KEYPAD_SECTION> 

restrictions 

Valid only in the context of the <KEYPAD_SECTlON> tag. 

required 

terminator 

<ENDKEYPAD> 

DESCRIPTION 

The < KEYPAD > tag allows you to specify an optional heading for a keypad 
diagram. If you use the DISPLAY keyword argument, the < KEYPAD > 
tag allows you to specify individual key labels as arguments to the tags 
<KEYPAD_ROW> and <KEYPAD_ENDROW> . For more information, refer to 
the descriptions of the <KEYPAD_ROW> and <keypad_endrow> tags in 
this chapter. 

EXAMPLES 

The following examples show two keypads. The first example does not 
include the DISPLAY keyword argument. The second example includes the 
DISPLAY keyword argument. To see other examples using the <KEYPAD> 
tag, refer to the description of the <KEYPAD_SECTlON> tag in this section. 
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<KEYPAD> 


<KEYPAD_SECTION> 

<KEYPAD>(Using the Command Keypad Function) 

<KEYPAD_ROW>(CL0SED\\\) 

<KEYPAD_ROW>(CL0SED\\\) 

<KEYPAD_ROW>(\\\) 

<KEYPAD_ROW>(\\\) 

<KEYPAD_ENDROW>(\\) 

<ENDKEYPAD> 

<ENDKEYPAD_SECTION> 

This example may produce the following output: 

Using the Command Keypad Function 

■□□□ 

■□□□ 

□□□□ 

nnU 

<KEYPAD_SECTION> 

<KEYPAD>(The Editing Keypad With Key Labels\DISPLAY) 

<KEYPAD_ROW>(PF1\PF2\PF3\PF4) 

<KEYPAD_ROW>(7\8\9\-) 

<KEYPAD_ROW>(4\5\6\.) 

<KEYPAD_R0W>(1\2\3\ ) 

<KEYPAD_ENDROW>(0\.\ENTER) 

<ENDKEYPAD> 

<ENDKEYPAD_SECTION> 


This example may produce the following output: 

The Editing Keypad With Key Labels 



<KEYPAD_SECTION> 

<KEYPAD>(The Editing Keypad With Key Labels and Blacked-in Keys\DISPLAY) 
<KEYPAD_ROW>(CL0SED\PF2\PF3\PF4) 

<KEYPAD_ROW>(7\8\9\-) 

<KEYPAD_ROW>(CL0SED\5\6\,) 

<KEYPAD_R0W>(1\2\3\ ) 

<KEYPAD_ENDROW>(0\.\ENTER) 

<ENDKEYPAD> 

<ENDKEYPAD_SECTION> 
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<KEYPAD> 


This example may produce the following output: 

The Editing Keypad With Key Labels and Blacked-in Keys 


1 

PF2 

PF3 

PF4 

7 

8 

9 

- 


5 

6 

' 

1 

2 

3 

ENTER 

0 
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< KEYPAD- 

_ENDROW> 

Displays the bottom row of an editing keypad that has up to three keys. 

FORMAT 

<KEYPAD_ENDROW> (col-1-arg \col-2-arg 

\ col-3-arg) 

ARGUMENTS 

col-1 -arg 
col-2-arg 
col-3-arg 

Represents one of the three keys that make up the bottom row in the 
editing keypad. Each column by default accepts one of the following three 
arguments: 

• CLOSED — This tag shades the key in that column. 

• NONE — No key appears in that column. 

• OPEN — This tag creates an unshaded box. This is the default. 

If you use the DISPLAY keyword argument to the < KEYPAD > tag, you can 
specify alphanumeric strings as individual key labels. 

related tags 

• < KEYPAD > 

• <KEYPAD_ROW> 

• <KEYPAD_SECTION> 

restrictions 

This tag can only be used in the context of a < KEYPAD-SECTION > tag. 

required 

None. 

terminator 


DESCRIPTION 

The <KEYPAD_ENDROW> tag creates three keys that are found on the bottom 
row of many calculator keypads. The first key is double in width; the second 
is standard size, and the third is connected with the last key in the previous 
keypad row. For more information, refer to the examples in the description of 
<KEYPAD_SECTlON> in this section. 


EXAMPLE 

See the example of the <keypad_section> tag. 
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<KEYPAD_ROW> 


<KEYPAD_ROW> 

Displays a row of an editing keypad that has up to four keys. 


FORMAT <KEYPAD_^ROW> (col-1-arg \col-2-arg 

\ col-3-arg \ col-4-arg} 


ARGUMENTS col-1-arg 

col‘2-arg 

col-3-arg 

col-4-arg 

Represents one of the four keys that make up a row in the editing keypad. 
Each column by default accepts one of the following three arguments: 

• CLOSED — This tag shades the key in that column. 

• NONE — No key appears in that column. 

• OPEN — This tag creates an unshaded box. This is the default. 

If you use the DISPLAY keyword argument in the < KEYPAD > tag, you can 
specify alphanumeric strings as individual key labels. 


related tags • <keypad> 

• <KEYPAD_ENDROW> 

• <KEYPAD_SECTION> 


restrictions This tag can only be used in the context of a < KEYPAD-SECTION > tag. 

When this tag is used just before the <KEYPAD_ENDROW> tag, the col-4-arg is 
ignored to leave room for the large ENTER key created by the third argument 
to the <KEYPAD_ENDROW> tag. See the example in the discussion of the 
< KEYPAD-SECTION > tag for more information. 


required None. 

terminator 


DESCRIPTION The <KEYPAD—ROW> tag creates a row of at most four keys in a keypad 

diagram. For more information, refer to the examples in the description of the 
<KEYPAD-SECTION > tag in this section. 
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<KEYPAD_ROW> 


EXAMPLE 

See the example in the discussion of the <KEYPAD_SECTiON> tag. 
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< KEYPAD. 

.SECTION > 

Begins a series of one or more keypad diagrams. 

FORMAT 

< KEYPAD-SECTION > 

related tags 

• < KEYPAD > 

• <KEYPAD_ENDROW> 

• <KEYPAD_ROW> 

restrictions 

You can only draft files containing keypad diagrams for devices that support 
graphics (such as laser printers). 

required 

terminator 

<ENDKEYPAD_SECTION> 

DESCRIPTION 

The <KEYPAD_SECTiON> tag enables the <keypad> , <keypad_endrow> , 
and <KEYPAD_ROW> tags to graphically depict one or more terminal 
editing keypads. Each of the keypads (or partial keypads) illustrated in a 
keypad section must be begun by the < keypad > tag and terminated by the 
<ENDKEYPAD> tag. 

EXAMPLES 

The following examples show several uses of the < KEYPAD-SECTION > tag. In 
the first example, notice how you use the <KEYPAD_ENDROW> to create the 
large sized keys found on many calculator keypads. 


<KEYPAD_SECTION> 

<KEYPAD>(The VT200 Series Editing Keypad) 
<KEYPAD_ROW>(\\\) 

<KEYPAD_ROW>(\\\) 

<KEYPAD_ROVl/>(\\\) 

<KEYPAD_ROW>(\\\) 

<KEYPAD_ENDROW>(\\) 

<ENDKEYPAD> 

<ENDKEYPAD_SECTION> 


This example may produce the following output. 

The VT200 Series Editing Keypad 


□□□ 


□□□ 


□□□ 


□□□ 


□□ 
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The following example shows two keypads created within a single keypad 
section. The first keypad shows a command keypad with two keys filled in. 
The second keypad is an irregularly shaped keypad. 

<KEYPAD_SECTION> 

<KEYPAD>(Using the Conunand Keypad Function) 

<KEYPAD_ROW> (CLOSEDWX) 

<KEYPAD_ROW>(CL0SED\\\) 

<KEYPAD_ROW>(\\\) 

<KEYPAD_ROW>(\\\) 

<KEYPAD_ENDROW>(\\) 

<ENDKEYPAD> 

<KEYPAD>(Using the SELECT Key) 

<KEYPAD_ROW>(\\\N0NE) 

<KEYPAD_ROW>(CL0SED\\\N0NE) 

<KEYPAD_ROW>(N0NE\\N0NE\N0NE) 

<KEYPAD_ROW>(\\\N0NE) 

<ENDKEYPAD> 

<ENDKEYPAD_SECTION> 

This example may produce the following output. 

Using the Command Keypad Function 

■□□□ 

■□□□ 

□□□□ 

nnU 


Using the SELECT Key 

□□□ 

□ 

□□□ 


The following example shows how to create a keypad with the key names 
placed on each keypad key. Note how the DISPLAY keyword argument is 
used with the < keypad > tag. 

<KEYPAD_SECTION> 

<KEYPAD>(The Editing Keypad With Key Labels\DISPLAY) 

<KEYPAD_ROW>(PF1\PF2\PF3\PF4) 

<KEYPAD_ROW>(7\8\9\-) 

<KEYPAD_ROW>(4\5\6\.) 

<KEYPAD_ROW>(1\2\3\ENTER) 

<KEYPAD_ENDROW>(0\.\ENTER) 

<ENDKEYPAD> 

<ENDKEYPAD_SECTION> 
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This example may produce the following output. 

The Editing Keypad With Key Labels 


PF1 

PF2 

PF3 

PF4 

7 

8 

9 

- 

4 

5 

6 

' 

1 

2 

3 

ENTER 

0 
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<KEY-PLUS> 

Creates a plus sign between keys in a key sequence example. 

FORMAT 

<KEY-PLUS> 

ARGUMENTS 

None. 

related tags 

• <KEY> 

• <KEY_SEQUENCE> 

• <KEY-TYPE> 

restrictions 

This tag can only be used in the context of the <KEY_SEQUENCE> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <KEY_PLUS> tag creates a plus sign between keys in a key sequence 
example. 


EXAMPLE The following example shows how you can use the <KEY_PLUS> tag to 

create a plus sign between the BREAK and FIO keys in the context of the 
<KEY_SEQUENCE> tag. 


<KEY_SEQUENCE> 

<KEY>(BREAK) <KEY_PLUS> <KEY>(F10) = Exit from Function. 

<ENDKEY_SEQUENCE> 

This example may produce the following output. 
I BREAK I + |F10| = Exit from Function. 
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<KEY_SEQUENCE> 

Begins a section containing one or more key representations. 

FORMAT 

<KEY_SEQUENCE> 

ARGUMENTS 

None. 

related tags 

• <CPOS> 

• <GRAPHIC> 

• <KEY> 

• <KEY_PLUS> 

• <KEY_TYPE> 

restrictions 

Not available within the context of the example-producing tags ( <CODE_ 
EXAMPLE> , <DISPLAY> , <SYNTAX> and SO on) or the <MATH> tag. 

required 

terminator 

<ENDKEY_SEQUENCE> 

DESCRIPTION 

The <KEY_SEQUENCE> tag labels an informal example of keys and sequences 
of keys, and enables two tags that make it easier for you to combine keys and 
text in your document. The two enabled tags are <KEY_PLUS> and <KEY_ 
TYPE> . For more information concerning these tags, refer to the program 
example in this section, or refer to the <KEY_PLUS> and <KEY_TYPE> tag 
descriptions in this section. 

EXAMPLES 

The following examples show how you can create informal examples of keys 
and key sequences in your documentation. The first example shows how the 
<KEY_PLUS> and the tag can be used. 

The second example shows how other tags can be used in a < KEY- 
SEQUENCE > tag section and then gives a sample of that output. 


<KEY_SEqUENCE> 

<key>(HELP) = <key>(PFl) <KEY_PLUS> <KEY>(PF2) 
<ENDKEY_SEQUENCE> 


This example may produce the following output. 
|HELP| = [PfTI + |PF2| 
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<KEY_SEQUENCE> 

The <CPOS>(q)uick brown fox 
jumped over the lazy dog. 

<KEY>(ADV)<KEY>(WORD) 

The quick <CP0S>(b)rown fox 
jumped over the lazy dog. 

<KEY>(W0RD) 

The quick brown <CP0S>(f)ox 
jimped over the lazy dog. 

<KEY>(DEL W) 

The quick brown <CP0S>( ) 
jumped over the lazy dog. 

<ENDKEY_SEQUENCE> 

This example may produce the following output. 

The quick brown fox 
jumped over the lazy dog. 

I ADV I WORD I 

The quick brown fox 

jumped over the lazy dog. 

I word] 

The quick brown fox 
jumped over the lazy dog. 

[PEL W| 

The quick brown _ 
jumped over the lazy dog. 
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<KEY_TYPE> 

Provides a descriptive label for keys within a key sequence. 

FORMAT 

< KEY-TYPE> (labeling-text-string 
\ key-text-string) 

ARGUMENTS 

labeling-text-string 

Labels the keys and text specified in the key-text-string argument. 

key-text-string 

Specifies keys and related text. 

related tags 

• <KEY_PLUS> 

• <KEY_SEQUENCE> 

• <GRAPHIC> 

restrictions 

This tag can only be used in the context of a <KEY_SEQUENCE> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <KEY_TYPE> tag provides a means of labeling a sequence of keys. For 
instance, if you discuss keys from various keyboards (such as the VT125, 
VT240, and so forth), you may wish to label the different types of keys as 
you describe them within a <KEY_SEQUENCE> example. 

The <KEY_TYPE> tag outputs the labelling-text-string argument in a bold face 
font and appends a colon ( :) to it. The key-text-string argument is output on 
the same line in the standard text font. 

E)(AMPLE 

The following example shows how you can use the <key_type> tag to label 
a sequence of keys. 


<KEY_SEQUENCE> 

<KEY_TYPE>(LK201\<KEY>(F10) = Exit from Function.) 
<ENDKEY_SEqUENCE> 


This example may produce the following output: 
LK201: |fio| = Exit from Function. 
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<l\/IESSAGE_SECTION> 

Begins a section of error message descriptions. 

FORMAT 

<MESSAGE_SECTION> 

ARGUMENTS 

None. 

related tags 

• 

< MESSAGE-TYPE > 


• 

<MSG> 


• 

<MSGS> 


• 

< MSG-TEXT > 

restrictions 

None. 

required 

< ENDMESS AGE-SECTION > 

terminator 




DESCRIPTION The < MESSAGE—SECTION > tag begins a message description section and 

enables the message tags listed as "related tags" in this tag description. 

Messages generally come in one of three forms: 

• A message text string only; for example, "System Resources Unavailable." 

• A message text string preceded by a text string identification code; for 
example, "%DlRECT-W-NOFlLES, no files found." 

• A message text string preceded by a numeric string identification code; for 
example, "%1288374 file lookup failed." 

You select the tags you need to use in the message description section based 

upon the following criteria: 

• The format your messages most closely resemble 

• The number of lines each message occupies on the terminal display 

Specify the format for your message section by using the <MESSAGE_TYPE> 

tag. The < message_type> tag accepts one of three keywords: 

• NOIDENT—Specifies that the message contains no message identification 
string and that only message text will be specified. 

• TEXTIDENT—Specifies that the message contains a text message 
identification string as well as message text. 
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• NUMIDENT—Specifies that the message contains a numeric message 
identification string as well as message text. 

Select one of two message labeling tags ( <MSG> or <MSGS> ), based upon 
the number of messages or message text lines you need to describe in a single 
tag. 

• <MSG> Describes a single message with one or two lines of message 
text. 

• <MSGS> Describes either a single message with up to nine lines of 
message text or up to four message identification string/message text 
pairs. 

Use the <MSG_TEXT> tag to describe the error messages. Each use of the 
< MSG-TEXT > tag creates a separate description section that you can label 
with a single word heading (such as "Facility" or "Severity"). If you do not 
specify a heading for this tag, it uses the heading, "Explanation:." You can 
use the <MSG_TEXT> as many times as you find necessary within the error 
message description section. 

To complete your error message section, repeat using the <MSG> (or 
<MSGS> ) and <MSG_TEXT> tags until you describe all of your messages. 
End the error message section by using the <ENDMESSAGE-SECTION > tag. 


EXAMPLES The following examples illustrate the two syntaxes available with the <MSG> 

tag and how they are specified. The second example also shows a sample 
use of the <MSGS> tag so you can compare the output of the <MSG> and 
<MSGS> tags. 

In the first example, the NOIDENT keyword argument is used with the 
<MESSAGE-TYPE > tag. Therefore, the <msg> tag only accepts two 
arguments. 

In the second example, the TEXTIDENT keyword is used with the 
< MESSAGE-TYPE > tag. Therefore, the <MSG> tags in this section 
accept one message identifier and up to two message text arguments. Note 
also that the <MSGS> tag used in this example accepts two pairs of message 
identifier/message text arguments. 

|] <MESSAGE_SECTION> 

<MESSAGE_TYPE>(NOIDENT) 

<MSG>(error initiating systemXinitialization file not found) 

<MSG_TEXT> 

The system could not begin operation because it could not find 
the system initialization file. 

<MSG_TEXT>(User Action) 

Check for the existence of the system initialization file. 

If it exists, check that it is in your current default directory. 

<ENDMESSAGE_SECTI0N> 
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This example may produce the following output: 

error initiating system 
initialization file not found 

Explanation: The system could not begin operation because it could not find 
the system initialization file. 

User Action: Check for the existence of the system initialization file. If it 
exists, check that it is in your current default directory. 

<MESSAGE_SECTION> 

<MESSAGE_TYPE>(TEXTIDENT) 

<MSG>(BCK-F-BADLNK\Incorrect directory back link\Directory not found) 

<MSG_TEXT>(Facility) VERIFY, Verify Utility 

<MSG_TEXT>(Severity) Fatal 

<MSG_TEXT> 

The Verify Utility could not process your command. Please check the 
syntax of your statement. 

<MSG_TEXT>(User Action) 

Check the syntax of the command, especially the directory specification, 
and reenter the command. 

<MSGS>(UAF-E-NAOFIL\unable to open file SYSUAF.DAT\-RMS-E-FNF\file not found) 

<MSG_TEXT> 

The AUTHORIZE Utility could not locate the file SYSUAF.DAT. 

<MSG_TEXT>(User Action) 

Check that your process is currently set to the system default directory, 

SYS$SYSTEM, and then reissue the command. 

<ENDMESSAGE_SECTION> 


This example may produce the following output. 

BCK-F-BADLNK, Incorrect directory back link 
Directory not found 

Facility: VERIFY, Verify Utility 

Severity: Fatal 

Explanation: The Verify Utility could not process your command. Please 
check the syntax of your statement. 

User Action: Check the syntax of the command, especially the directory 
specification, and reenter the command. 

UAF-E-NAOFIL, unable to open file SYSUAF.DAT 
-RMS-E-FNF, file not found 

Explanation: The AUTHORIZE Utility could not locate the file SYSUAF.DAT. 

User Action: Check that your process is currently set to the system default 
directory, SYS$SYSTEM, and then reissue the command. 
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<MESSAGE_TYPE> 


Establishes the format for error messages in the context of the 
<MESSAGE_SECTION> tag. 


FORMAT 

<MESSAGE_TYPE> (type-keyword) 

ARGUMENTS 

type-keyword 

Identifies the error message format and the number of arguments to pass to 
the <MSG> and <MSGS> tags. These keyword arguments can be any of the 
following formats: 


• NOIDENT — Indicates that only message text will be used as arguments 
to the <MSG> or <MSGS> tag. This is the default. 


• TEXTIDENT — Indicates that the message has two parts, a text 
identification string and a line of message text. These two arguments 
are then required by the <MSG> or <MSGS> tags. 


• NUMIDENT — Indicates that the message has two parts, a numeric 
identification string and a line of message text. These two arguments are 
then required by the <MSG> or <MSGS> tags. 

related tags 

• < MESSAGE-SECTION > 


• <MSG> 


• <MSGS> 


• <MSG_TEXT> 

restrictions 

This tag can only be used in the context of a <message_section> tag. 

required 

terminator 

None. 


DESCRIPTION The <MESSAGE_TYPE> tag establishes the error message format for all 

subsequent error message descriptions. The format determines the number of 
arguments passed to the <MSG> and <MSGS> tags. 


For a complete description of the message section tags, refer to the description 
of <MESSAGE_SECTlON> in this section. 


EXAMPLE 

See the example in the discussion of the <MESSAGE_SECTlON> tag. 
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<MSG> 

Formats the text of a message within a series of error message 
descriptions. 

FORMAT 

< MSG > (message-text-1[ \ message-text-2]) 

< MSG > (message-id \ message-text-1 

[ \ message-text-2]) 

ARGUMENTS 

message-id 

Specifies a unique message identification string. This argument can be either 
a text string or a numeric string. You can only specify this keyword argument 
if you have specified either the NUMIDENT or the TEXTIDENT keyword 
argument to the < MESSAGE_TYPE> tag. 

message-text-1 

Is the text of the message. 

message-text-2 

Is the optional second line of the text of the message. 

related tags 

• < MESSAGE-SECTION > 

• <MESSAGE_TYPE> 

• <MSG_TEXT> 

• <MSGS> 

restrictions 

This tag can only be used in the context of a < MESSAGE-SECTION > tag. 

required 

terminator 

None. 


DESCRIPTION Use the <MSG> tag to specify the parts of a single error message. If you are 

using the NOIDENT keyword argument to the < MESSAGE _TYPE> tag, or if 
you do not specify the < MESSAGE _TYPE> tag, you must use the first syntax 
listed. 

If you are using either the TEXTIDENT or NUMIDENT keywords as 
arguments to the < message _type> tag, you must use the second syntax 
listed. 

The message-id argument corresponds to the %FAC-S-IDENT portion of a 
system or application message in the VMS operating system programming 
environment. 
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<MSG> 


If you are using the NUMIDENT format, the message-id argument must 
be a numeric message identification string of not more than six picas 
(approximately ten characters) in length. If you are using the TEXTIDENT 
format, the message-id argument has a comma (,) placed between it and the 
following message-text argument. 

For a complete description of the message section tags, refer to the description 
of <MESSAGE_SECTI0N> in this section. 


EXAMPLE 

See the example in the discussion of the <MESSAGE_SECTlON> tag. 
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<MSGS> 

<MSGS> 

Formats the text of one or more messages within a series of error 
message descriptions. 

FORMAT 

<MSGS> (message-‘text-1[\ message-text-2 . . . 

\ message-text-9]) 

<MSGS> (message-id-1 \ message-text-1 

[\ message-id-2 \ message-text-2] 

[ \ message-id-3 \ message-text-3] 

[ \ message-id-4 \ message-text-4]) 

ARGUMENTS 

message-id-n 

Specifies a unique message identification string. This argument can be either 
a text string or a numeric string. You can only specify this keyword argument 
if you have specified either the NUMIDENT or the TEXTIDENT keyword 
arguments to the < MESSAGE-TYPE > tag. 

message-text-n 

Is the text of the message. 

related tags 

• < MESSAGE-SECTION > 

• < MESSAGE-TYPE > 

• <MSG> 

• < MSG-TEXT > 

restrictions 

This tag can only be used in the context of a < MESSAGE-SECTION > tag. 

required 

terminator 

None. 

DESCRIPTION 

The <MSGS> tag specifies the parts of a single error message. If you are 
using the NOIDENT keyword argument to the < MESSAGE-TYPE > tag, or if 
you do not specify the < MESSAGE-TYPE > tag, you must use the first syntax 
listed. 


If you are using either the TEXTIDENT or NUMIDENT keywords as 
arguments to the < MESSAGE _TYPE> tag, you must use the second syntax 
listed. Note that using this syntax, the message-id and message-text arguments 
must be specified as pairs. 
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The message-id argument corresponds to the %FAC-S-IDENT portion of a 
system or application message in the VMS operating system programming 
environment. 

If you are using the NUMIDENT format, the message-id argument must 
be a numeric message identification string of not more than six picas 
(approximately ten characters). If you are using the TEXTIDENT format, the 
message-id argument has a comma (,) placed between it and the following 
message-text argument. 

For a complete description of the message section tags, refer to the description 
of < MESSAGE-SECTION > in this section. 


EXAMPLE 


See the example in the discussion of the < message-Section > tag. 
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<MSG_TEXT> 


<MSG_TEXT> 


Labels text that describes a message in a <message_section> tag 
section. 


FORMAT 

<MSG_TEXT> [(alternate-heading)] 

ARGUMENTS 

alternate-heading 

Specifies the label for the text of the message description. This text 
automatically has a colon (:) appended to the end of it. If you do not 
specify this argument, the default heading is "Explanation:." 

restrictions 

Valid only within the context of the < MESSAGE-SECTION > tag. 

required 

terminator 

< ENDMESS AGE-SECTION > 

The text labeled by the <MSG-TEXT> tag is terminated either by the next 
<MSG> or <MSGS> tag, or by the < ENDMESS AGE-SECTION > tag. 

DESCRIPTION 

The <MSG_TEXT> tag labels a message description within an error message 
section. The text of this description begins after the <MSG-TEXT> tag and 
continues until the next message section tag is encountered. 

If you want to use this tag to label various portions of the message 
explanation, you can do so by specifying this tag several times using various 
alternate headings. 

For example, first you could have a brief explanation of the message under 
the default heading "Explanation:." Then you could specify the <MSG-TEXT> 
tag again, with the alternate heading of "User Action." This use of the <MSG- 
TEXT> tag labels the tasks the user should perform to correct the condition 
that caused the error message. Note that when specifying alternate headings, 
a colon (:) is supplied at the end of the heading. 

For a complete description of all the message section tags, refer to the 
description of the < message-SECTION > tag in this section. 

EXAMPLE 

See the example in the discussion of the < MESSAGE-SECTION > tag. 
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<PARAMDEF> 

Begins the text that defines an item in a parameter definition list. 

FORMAT 

<PARAMDEF> 

ARGUMENTS 

None. 

related tags 

• <PARAMDEFLIST> 

• <PARAMITEM> 

restrictions 

Valid only in the context of the <PARAMDEFLIST> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <PARAMDEF> tag is used within a parameter definition list to label the 
beginning of the text that defines a list item. This text describes the item listed 
by the previous <PARAMITEM> tag. The text begun by the <PARAMDEF> tag 
is terminated by the next <PARAMITEM> or <ENDPARAMDEFLIST> tag. 

EXAMPLE 



See the example in the discussion of the <PARAMDEFLIST> tag. 
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<PARAMDEFLIST> 


<PARAMDEFLIST> 


Begins a definition list of parameters or arguments. 


FORMAT 


<PARAMDEFLIST> [( 


alternate-heading 

NOHEAD 

NONE 



ARGUMENTS alternate-heading 

Specifies a heading to override the current default text heading. The default 
heading for the <PARAMDEFLIST> tag can vary. See the description section 
for more information on default parameter definition list headings. 

NOHEAD 

Suppresses the output of the default heading for the <paramdeflist> tag, 

NONE 

Causes the text "None." to be output beneath the heading for the parameter 
definition list to indicate that no parameters are available. Note that when 
using the NONE keyword the <ENDPARAMDEFLIST> tag should not be used. 


related tags • <argdeflist> 

• <QUALDEFLIST> 

• <PARAMDEF> 

• <PARAMITEM> 

• <SET_TEMPLATE_HEADING> 

• The global < DEFINITION-LIST > tag 


required 

terminator 


<ENDPARAMDEFLIST> 

Required unless the NONE keyword was specified as an argument to the 
<PARAMDEFLIST> tag. 


restrictions None. 


DESCRIPTION The <PARAMDEFLIST> tag creates a definition list of parameters or 

arguments.This tag is available both inside and outside the context of the 
reference templates. 
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<PARAMDEFLIST> 


The <PARAMDEFLIST> tag is similar in format and syntax to the global 
<DEFINITI0N_LIST> tag. See The VAX DOCUMENT User Manual, Volume 1 
for more information on the <DEFiNlTlON_LlST> tag. The <PARAMDEFLIST> 
tag enables two tags to create a parameter definition list. The <PARAMITEM> 
tag labels the list item being defined, and the <PARAMDEF> tag begins the 
definition of the list item. 

A default heading is provided when the <paramdeflist> tag is used 
within a reference template; no default heading is provided when the 
<PARAMDEFLIST> tag is used outside a reference template. 

You can create your own heading for an individual parameter definition list 
by specifying that heading as the alternate-heading argument. A heading 
specified in this way overrides any existing default headings. 

Use the <SET_template_heading> tag to alter the default headings used by 
all subsequent <PARAMDEFLIST> tags. See the reference description of the 
<SET_TEMPLATE_HEADING> tag for more information. 

The default headings for the <PARAMDEflist> are listed by their context in 
the following informal table. 


Context 

Default Heading 

Command Template 

Parameters 

Routine Template 

Arguments 

Tag Template 

Arguments 

Statement Template 

No default heading 

Outside of a template 

No default heading 


EXAMPLES The following examples show variations on the use of the <PARAMDEFLIST> 

tag. 

This chapter uses the Tag template for its reference descriptions. Within 
this template, the heading for a parameter definition list is defined as 
"Arguments." You can see a sample of this heading just after the format 
section at the start of this tag description. 

The following example uses the NOHEAD argument to the <paramdeflist> 
tag to suppress the output of a heading within a template. If this example 
were coded outside of a template, there would be no default heading for the 
parameter definition list, and so there would be no need to use the NOHEAD 
argument to suppress a heading. 

Q The system maintains logical names and their associated 
equivalence strings in two types of tables: 

<PARAMDEFLIST>(NOHEAD) 

<PARAMITEM>(process-private) 

<PARAMDEF>These tables contain logical names that are available only 
to your process. 

<PARAMITEM>(shareable) 

<PARAMDEF>These tables contain logical names that are available to other 
processes on the system. 

<ENDPARAMDEFLIST> 
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<PARAMDEFUST> 


This example may produce the following output: 

The system maintains logical names and their associated equivalence strings 
in two types of tables: 

process-private 

These tables contain logical names that are available only to your process. 

shareable 

These tables contain logical names that are available to other processes on the 
system. 

The following example shows how to use the global < ALIGN-AFTER > tag for 
additional formatting flexibility in the parameter definition list. Note that this 
<PARAMDEFLIST> tag is used within the Command template and so has the 
default heading "Parameters." 

<COMMAND_SECTION> 


<PARAMDEFLIST> 

<PARAMITEM>(STATUS;arg\ 

<ALIGN_AFTER>(STATUS:)C0MMAND\ 

<ALIGN_AFTER>(STATUS:)TASK) 

<PARAMDEF>Specifies whether status information is to be returned 
from the RUN command. 

<ENDPARAMDEFLIST> 

<ENDC0MMAND_SECTI0N> 

This example may produce the following output. 


PARAMETERS STATUS.arg 

COMMAND 

TASK 

Specifies whether status information is to be returned from the RUN 
command. 



SOFTWARE Doctype Tag Reference 

<PARAMITEM> 


<PARAMITEM> 




Labels one to seven items to be defined in a parameter definition list. 

FORMAT 


\ item-2 




\ item-3 



<PARAMITEM> (item-1 

\ item-4 
\ item-5 
\ item-6 

) 



. \ item-7 . 


ARGUMENTS 

item-n 

Specifies the item in the parameter list to be defined. This tag accepts a 
minimum of one item-n argument and a maximum of seven item-n arguments. 
When more than one argument is specified, each subsequent item-n argument 
after the initial argument is formatted flush left under the first argument. 

related tags 

• <PARAMDEFLIST> 




• <PARAMDEF> 



restrictions 

Valid only in the context of the <paramdeflist> tag. 


required 

terminator 

<PARAMDEF> 




DESCRIPTION Use the <paramitem> tag to specify each of the items to be defined in a 

parameter list. One to seven arguments can be specified as items requiring 
a single definition in the parameter definition list. If more than one item-n 
argument is specified, the item-n arguments are stacked from top to bottom in 
the order in which they were specified. 

If you need to format the item-n arguments differently than the default flush 
left formatting, you can use the global < align _after> tag. A sample use 
of this tag is illustrated in the following example. See The VAX DOCUMENT 
User Manual, Volume 1 for more information on the < align_after> tag. 
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< PAR AM ITEM > 


EXAMPLE The following example shows how to use the global <ALIGN_AFTER> 

tag within the context of a parameter definition list for special formatting 
purposes. Note how it is used outside of the <PARAMITEM> tag. 


<PARAMDEFLIST>(NOHEAD) 

<PARAMITEM>(STATUS:arg\ 

<ALIGN_AFTER>(STATUS:)C0MMAND\ 

<ALIGN.AFTER>(STATUS:)TASK) 

<PARAMDEF>Specifies whether status information is to be returned 
from the RUN command. 

<ENDPARAMDEFLIST> 


This example produces the following. 

STATUS-.arg 

COMMAND 

TASK 

Specifies whether status information is to be returned from the RUN 
command. 
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<QPAIR> 


<QPAIR> 

Labels a qualifier pair within a qualifier format list. 

FORMAT 

<QPAIR> (qualifier-name \ default-qualifier-name} 

ARGUMENTS 

qualifier-name 

The command qualifier to be listed. A common convention indicates the 
negative form of the qualifier by placing brackets around the negative prefix, 
as in "[NO]CHECK." 

defauit-quaiifier-name 

The default value of the qualifier. 

related tags 

• <QUAL_LIST> 

• <QUAL_LIST_HEADS> 

restrictions 

Valid only within the context of a <QUAL_LIST> tag. 

required 

terminator 

None. 


EXAMPLE 


See the example in the discussion of the <QUAL_LIST> tag. 






SOFTWARE Doctype Tag Reference 

<QUAL_LIST> 


<QUAL_LIST> 


Begins a qualifier summary list. 


FORMAT <QUAL_LIST>/^farg-7 \arg-2 \WIDE)] 


ARGUMENTS arg-1 

The first argument can be one of the following: 

• alternate-heading —Causes this text to be used instead of the default 
heading in column one, "Command Qualifiers." This default heading can 
be modified or suppressed by using the <QUAL_LIST_DEFAULT_HEADS> 
tag. 

• NONE-—Indicates that there are no qualifiers or defaults and causes the 
text "None." to appear under the default headings for columns one and 
two ("Command Qualifiers" and "Defaults"). 

• SPECIAL—Labels an unusual case and causes VAX DOCUMENT to 
expect a value in the second argument that will set the width of the first 
qualifier column. 

arg-2 

The second argument can be one of the following: 

• WIDE—Causes the margins to be adjusted to accommodate a wide list. 

• alternate-heading —Causes this text to be used in column two in place of 
the default heading "Defaults." This default heading can be modified or 
suppressed by using the <QUAL_LIST_DEFAULT_HEADS> tag. 

• column-width —Provides VAX DOCUMENT with the size in picas of the 
desired width of the first column (there are six picas to an inch). This 
value must be a nonzero positive integer and can be used only when the 
first argument is SPECIAL. 

WIDE 

Causes the margins to be adjusted to accommodate a wide list. This third 

argument is used only in the two following cases: 

• When the first two arguments have been used to specify headings for 
columns one and two. 

• When the first two arguments have been used to specify a special list and 
the width of the first column. 


related tags 


• <QUAL_LIST_HEADS> 

• <QUAL_LIST_DEFAULT_HEADS> 

• <QPAIR> 
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<QUAL_UST> 


restrictions 


required 

terminator 


DESCRIPTION 


If you use the SPECIAL argument, you must use the <QUAL_LIST_HEADS> 
tag to specify headings for the qualifier list. 


<ENDQUAL_LIST> 


A qualifier summary list provides a short table listing the qualifiers that are 
applicable for a system command. It is an optional part of the command 
template, but it can be used in any context in a SOFTWARE doctype 
document. In the context of the command template, it provides a brief 
listing of qualifiers for quick look-up. 

The arguments you specify to the <QUAL_LIST> tag provide you with 
formatting flexibility, and the choice of overriding the default headings that 
are output. 

• When you specify the tag with no arguments, the column widths are 
set using the doctype design's default settings, and the default headings 
"Command Qualifiers" and "Defaults" are output. 

• When you specify text in the arguments to the <qual_list> tag, the 
default headings are replaced: 

<QUAL_LIST>(Subsystem QualifierXComment) 

This changes the default heading for this qualifier summary list only. 

• You can override the default headings for all qualifier summary lists 
in your document by using the <QUAL_LIST_DEFAULT_HEADS> tag, as 
follows: 

<GlUAL_LIST_DEFAULT_HEADS>(Subsystem Qualifier\Comment) 

To suppress either heading, enter the alternate heading text as a null 
argument: 

<QUAL_LIST_DEFAULT_HEADS>(\) 

• If items in the second column of your list result in output that does not fit 
horizontally in the SOFTWARE design you are using, you can specify the 
keyword argument WIDE in any of the following positions: 

<QUAL_LIST>(WIDE) 

This example uses the default headings, and shifts both columns of the 
list to the left, as far left as the doctype design allows. 

<qUAL_LIST> (heading-text\WIDE) 

This example modifies the default heading for the first column, uses the 
default heading for the second column, and shifts both columns of the list 
to the left, as far left as the document design allows. 

<qUAL_LIST> (heading-text\second-heading-text\VlfIDE) 

This example modifies the default headings for both the first and second 
columns, and shifts both columns of the list to the left, as far left as the 
doctype design allows. 
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<QUAL_LIST> 


<QUAL_LIST>(SPECIAL\18) 

<QUAL_LIST_HEADS>(Qualifiers) 

If the default column width of the first column of the qualifier summary 
list is too narrow (for example, when qualifier names are long or 
include lengthy argument specifications), you can widen that column 
by specifying the SPECIAL keyword as the first argument to the <QUAL_ 
LIST> tag. 

The <QUAL_LIST> tag will then accept the column-width argument as a 
second argument that specifies the width of the first column of the list in 
picas (there are six picas to an inch). If you use the <qual_list> tag 
in this manner, you must explicitly enter the headings for the qualifier 
summary list using the <QUAL_list_heads> tag. 


EXAMPLES The following example shows how to use the <QUAL_LIST> tag to create a 

qualifier summary list. 

n <qUAL_LIST> 

<QPAIR>(/B00K\None.) 

<QPAIR>(/[NO]CHECK\/CHECK) 

<QPAIR>(/[NO]FAMILY=keyword\/NOFAMILY) 

<qPAIR>(/OUTPUT=file-spec\/OUTPUT=input-file-name) 

<qPAIR> (/PR0FILE=file-spec\None.) 

<qPAIR>(/TYPE=keyword\See text.) 

<ENDqUAL_LIST> 


This example may produce the following output. 




Command Qualifiers 

/BOOK 

/[NOJCHECK 

/[NOJFAMIL Y=keyword 

/OUTPUT=file-spec 

/PROFILE=file-spec 

/TYPE=keyword 


Defaults 

None. 

/CHECK 

/NOFAMILY 

/OUTPUT=input-file-name 

None. 

See text. 


The following example shows how you can control the headings of the two 
columns of output by specifying the headings you want in arguments one 
and two. Compare the results here with the example in the discussion of the 
<QUAL_LIST_HEADS> tag. 


<qUAL_LIST> (Input Save Set QualifiersXDefault) 
<qPAIR> (/[NO]REWIND\/REWIND) 

<qPAIR>(/SAVE_SET\None.) 
<qPAIR>(/SELECT=(file-8pec[....])\None.) 
<ENDqUAL_LIST> 


This example may produce the following output: 


Input Save Set Qualifiers Default 

/[NOJREWIND /REWIND 

/SAVE-SET None. 

/SELECT=(file-spec[, ... 7) None. 
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<QUAL_LIST_DEFAULT_HEADS> 

Modifies the default heading used by the <qual_list> tag. 

FORMAT 

<QUAL_LIST_DEFAULT_HEADS> (heading-1 

\ heading-2) 

ARGUMENTS 

heading-1 

Specifies the default heading text for the first column. If this argument is 
specified as null, no first column heading is output. 

heading-2 

The default heading text for the second column. If this argument is specified 
as null, no second column heading is output. 

related tags 

• <QUAL_LIST> 

• < QUAL _LIST_HE ADS> 

• <QPAIR> 

restrictions 

Valid only within the context of a <QUAL_LIST> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <QUAL_LIST_DEFAULT_HEADS> tag lets you modify or suppress the 
default headings used by the <QUAL_list> tag. If you specify the heading-1 
or heading-2 arguments to this tag as null, the appropriate default heading 
(either the first or the second) is set to null and that heading is not output. 
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<QUAL 

_LIST_HEADS> 

Labels the headings you want to use for one or both of the columns in a 

qualifier format list when <quai_list> (SPECIAL) is used in unusual cases 

for formatting control. 

FORMAT 

<QUAL_LIST_HEADS> (heading-1 \ heading-2) 

ARGUMENTS heading-1 

Specifies the heading text for the left column. 

heading-2 

Specifies the heading text for the right column. If you do not specify this 
heading, you will obtain the default heading, "Defaults." 

related tags 

• <QUAL_LIST> 

• <QPAIR> 

restrictions 

Valid only within the context of a <QUAL_LIST> tag. 

required 

terminator 

None. 

EXAMPLE 

The following example shows how to use the <QUAL_LIST_HEADS> tag to 
create qualifier summary list headings when the <QUAL_LIST> tag is used 
with the SPECIAL argument. 


<P>Thie following is a partial list of the qualifiers you may use 
with the BACKUP command: 

<QUAL_LIST>(SPECIAL\18) 

<QUAL_LIST_HEADS>(Output File Qualifiers\Qualifier Defaults) 

<QPAIR>(/OWNER.UIC[=option]\/OWNER_UIC=DEFAULT) 

<QPAIR>(/REPLACE\None.) 

<ENDQUAL_LIST> 

This example may produce the following output. 

The following is a partial list of the qualifiers you may use with the BACKUP 
command: 


Output File Qualifiers 

/OWNER-UIC[=option] 

/REPLACE 


Qualifier Defaults 

/OWNER-UIC=DEFA UL T 
None. 
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<QUALDEF> 

Begins the text that defines an item in a qualifier definition list. 

FORMAT 

<QUALDEF> 

ARGUMENTS 

None. 

related tags 

• <QUALDEFLIST> 

• <QUALITEM> 

restrictions 

Valid only within the context of a <QUALDEFLIST> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <QUALDEF> tag is used within a qualifier definition list to label the 
beginning of the text that defines a list item. This text describes the item 
listed by the previous <QUALITEM> tag. The text begun by the <QUALDEF> 
tag is terminated by the next <QUALITEM> or <ENDQUALDEFLIST> tag. 

EXAMPLE 



See the example in the discussion of the <qualdeflist> tag. 






SOFTWARE Doctype Tag Reference 

<QUALDEFLIST> 


<QUALDEFLIST> 


Begins a definition list describing command qualifiers. 


FORMAT 


<QUALDEFLIST> [({ 


alternate-heading 

NOHEAD 

NONE 



ARGUMENTS alternate-heading 

Specifies a heading to override the current default text heading. The default 
heading provided by VAX DOCUMENT for the <QUALDEFLIST> tag can 
vary. See the description section for more information on default qualifier 
definition list headings. 

NOHEAD 

Suppresses the output of the default heading for the <QUALDEFLIST> tag. 

NONE 

Causes the text "None." to be output beneath the heading for the qualifier 
definition list to indicate that no qualifiers are available. Note that when 
using the NONE keyword the <ENDQUALDEFLIST> tag should not be used. 


related tags • <argdeflist> 

• <PARAMDEFLIST> 

• <QUALDEF> 

• <QUALITEM> 

• <SET_TEMPLATE_HEADING> 

• The global <definition_list> tag 


required 

terminator 


< ENDQUALDEFLIST > 

Required unless the NONE keyword was specified as an argument to the 
<QUALDEFLIST> tag. 


restrictions None. 


DESCRIPTION The <QUALDEFLIST> tag creates a definition list of command qualifiers; it is 

similar in format and syntax to the global <DEFlNlTiON_LlST> tag. See The 
VAX DOCUMENT User Manual, Volume 1 for more information. 
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The <QUALDEFLIST> tag enables two tags to create a qualifier definition list. 
The <QUALITEM> tag labels the list item being defined, and the <qualdef> 
tag begins the definition of the list item. These tags are functionally the 
same as the <deflist_item> and <deflist_def> tags enabled by the 
global <DEFiNiTiON_LiST> tag. A default heading is provided when the 
<QUALDEFLIST> tag is used within a reference template; no default heading 
is provided when the <QUALDEFLIST> tag is used outside of a reference 
template. 

You can create your own heading for an individual qualifier definition list 
by specifying that heading as the alternate-heading argument. A heading 
specified in this way overrides any existing default headings. 

Use the <set_template_heading> tag to alter the default headings used 
by all subsequent <QUALDEFLIST> tags. See the reference description of the 
< SET-TEMPLATE-HEADING > tag for more information. 

The default headings for the <QUALDEFLIST> are listed by their context in 
the following informal table. 


Context 

Default Heading 

Command Template 

Qualifiers 

Tag Template 

Qualifiers 

Routine Template 

No default heading 

Statement Template 

No default heading 

Outside of a template 

No default heading 


EXAMPLE The following example shows a qualifier definition list within the context of 

the Command template. 

<COMMAND_SECTION) 


<QUALDEFLIST> 

<QUALITEM>(/L0G\/N0L0G (D)) 

<QUALDEF>Specifies whether or not output logging should be used. 
The default is /NOLOG. 

<QUALITEM>(/ECH0\/N0ECH0 (D)) 

<QUALDEF>Specifies whether or not input echoing should be used. 
The default is /NOECHO. 

<ENDqUALDEFLIST> 


<ENDCOMMAND_SECTIQN> 
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<QUALDEFLIST> 


This example may produce the following output: 


/LOG 

/NOLOG (D) 

Specifies whether or not output logging should be used. The default is 
/NOLOG. 

/ECHO 
/NOECHO (D) 

Specifies whether or not input echoing should be used. The default is 
/NOECHO. 
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<QUALITEM> 




Labels one to seven items to be defined in a qualifier definition list. 

FORMAT 


\ item-2 




\ item-3 



<QUALITEM> (item-1 

\ item-4 
\ item-5 
\ item-6 

) 



. \ item-7 . 


ARGUMENTS 

item-n 

Specifies the item in the qualifier list to be defined. This tag accepts a 
minimum of one item-n argument and a maximum of seven item-n arguments. 
When more than one argument is specified, each subsequent item-n argument 
after the initial argument is formatted flush left under the first argument. 

related tags 

• <QUALDEFLIST> 




• <QUALDEF> 



restrictions 

Valid only within the context of a <QUALDEFLIST> tag. 

required 

terminator 

<QUALDEF> 




DESCRIPTION Use the <QUALITEM> tag to specify each of the items to be defined in a 

qualifier list. One to seven arguments can be specified as items requiring 
a single definition in the qualifier definition list. If more than one item-n 
argument is specified, the item-n arguments are stacked from top to bottom in 
the order in which they were specified. 

You may find it convenient to use the item-n arguments to the 
<QUALDEFLIST> tag in pairs. The first item in the pair could be the positive 
form of the qualifier, and the second item could be the negative form of 
the qualifier (for example, /LOG and /NOLOG). Use the global <ALIGN_ 
AFTER> to format the item-n arguments differently than the default flush left 
formatting. 

A sample use of this tag is illustrated in the following example. See The 
VAX DOCUMENT User Manual, Volume 1 for more information on the 
<ALIGN_AFTER> tag. 
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<QUALITEM> 


EXAMPLE The following examples show several uses of the <qualitem> tag. The first 

two uses of the <QUALITEM> tag show how positive and negative forms of 
a qualifier may be grouped together. The third use of the <QUALITEM> tag 
shows how the global <ALIGN_AFTER> tag can be used to achieve special 
formatting. 

<QUALDEFLIST> 

<C|UALITEM>(/L0G\/N0L0G (D)) 

<qUALDEF>Specifies whether or not output logging should be used. 

The default is /NOLOG. 

<QUALITEM>(/ECH0\/N0ECH0 (D)) 

<QUALDEF>Specifies whether or not input echoing should be used. 

The default is /NOECHO. 

<qUALITEM>(/DEVICE=device-type\ 

<ALIGN_AFTER>(DEVICE=)VT100\ 

<ALIGN_AFTER>(DEVICE=)VT220) 

<qUALDEF>Specifies the type of device to be used. 

<ENDqUALDEFLIST> 


This example may produce the following output. 


QUALIFIERS /LOG 

/NOLOG (D) 

Specifies whether or not output logging should be used. The default is 
/NOLOG. 

/ECHO 
/NOECHO (D) 

Specifies whether or not input echoing should be used. The default is 
/NOECHO. 

/DEVICE=device-type 

VT100 

VT220 

Specifies the type of device to be used. 
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<RUNNING 

i_FEET> 

Creates a single line heading at the bottom of each page in a document 
processed using the SOFTWARE.SPECIFICATION doctype. 

FORMAT 

<RUNNING_FEET> (title-text} 

ARGUMENTS 

title-text 

Specifies the text to be used as a running heading at the foot of the page. 

related tags 

• < RUNNING-TITLE > 

restrictions 

Available only in the SOFTWARE.SPECIFICATION doctype. 

required 

terminator 

None. 

DESCRIPTION 

Use the <runninG-FEET> tag to place a heading at the bottom of every 
page. This heading is called a "footer" because it appears at the foot of 
the page. When the same footer is used for several pages, the footers are 
collectively called "running feet." 

This tag accepts one argument, which is the text which should appear as the 
heading at the bottom of the page. This text is output exactly as entered, 
including spacing and capitalization. 

Use the <runninG-TITLE> tag to create a heading at the top of the 
page. See the reference description of the <runninG-TITLE> tag for more 
information on that tag. 


EXAMPLE The following example shows how to use the < RUNNING—FEET > tag to place 

the heading "Getting the Piece of Paper" at the bottom of each page. Note 
that the running footer will be output exactly as entered. 


<RUNNING_FEET>(Getting the Piece of Paper) 

<HEAD2>(Getting the Piece of Paper) 

<P> 

You can buy clean paper in most major supermarkets, department stores, 
and hardware stores. You should try to get ruled paper so that 
your letter will be neat and easy to read. 
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<RUNNING_TITLE> 


Creates a one- or two-line running heading at the top of each page in a 
document processed using the SOFTWARE.SPECIFICATION doctype. 


FORMAT 

( OFF ) 

<RUNNING_TITLE> ( title-1 [\title-2] ) 

. [\ FIRST-PAGE] . 

ARGUMENTS 

title-1 

Specifies the text of a running title. If a two-line title is specified, this title is 
output on the upper title line. 


title-2 

Specifies the optional bottom line of a running title that has two lines. 


FIRST-PAGE 

Specifies that the running title is to begin output on the first output page. If 
this keyword is not specified, the running title is output on the page after the 
current page. 


OFF 

Specifies that any existing running titles created using the < RUNNING-TITLE > 
tag should be disabled for the page on which this tag occurs and on any 
subsequent pages. 

related tags 

• <RUNNING_FEET> 

restrictions 

Valid only in the SOFT WARE. SPECIFICATION doctype. 

required 

terminator 

None. 

DESCRIPTION 

Use the < RUNNING-TITLE > tag to specify a one- or two-line title at the top 
of the page. Use the FIRST-PAGE argument to the <runninG-TITLE> tag to 
begin the title lines on the first page of output, rather than on the page after 
the current page as is the default. 


Use the OFF argument to disable any existing running titles created using the 
<RUNNING_TITLE> tag. These titles will then be disabled for the page on 
which this tag occurs and on any subsequent pages. 

Use the <running_feet> tag to create a heading that appears at the bottom 
of the page. See the reference description of the <RUNNING_FEET> tag for 
more information on that tag. 


14-73 





SOFTWARE Doctype Tag Reference 

<RUNNING_TITLE> 


EXAMPLES The following example shows how to use the <running_title> tag to 

create the two-line running title "An E. B. Bartz Course:" and "Writing Quality 
Correspondence." Since the FIRST-PAGE argument is used, the two-line 
running title will appear at the top of the first page. 

Q <RUNNING_TITLE>(An E. B. Bartz Course:\Writing Quality Correspondence\FIRST_PAGE) 

<HEADl>(How to Write a Letter) 

<P> 

The first thing that you should do in writing a letter is to get 
a clean piece of paper and a well-sharpened pencil. 

The following example shows how you can disable a running title by using 
the OFF argument to the <RUNNING_TITLE> tag. 

2 <C0MMENT>(turn off running titles for the following example page) 

<RUNNING_TITLE>(OFF) 

<HEAD>(An Example of a Letter) 
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<SIGNATURES> 

Begins a list of signatures that are to appear in the front matter portion of 
a document processed using the SOFTWARE.SPECIFICATION doctype. 

FORMAT 

<SIGNATURES> [(NEWPAGE)] 

ARGUMENTS 

NEWPAGE 

Specifies that the signature list is to begin on a new page. 

related tags 

• <AUTHOR> 

• < BYLINE > 

• The global <front_matter> tag 

restrictions 

Available only in the SOFTWARE.SPECIFICATION doctype following the 
global <FRONT_MATTER> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <SIGNATURES> tag begins a list of persons who are to sign a document. 
Each person's name is listed by using the < BYLINE > tag following the 
<SIGNATURES> tag. The <BYLINE> tag places the name of the person, and 
additional information about that person (such as his or her title or affiliation), 
below a line on which the person is to sign. 

See the reference description of the < BYLINE > tag for more information on 
that tag. 


EXAMPLE 

See the example in the description of the < BYLINE > tag. 
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<SYNTAX> 


<SYNTAX> 

Allows you to use special characters to describe language syntaxes. 

FORMAT 

<SYNTAX> [( i heading-text [\ WIDE] 1 ii 
' 1 WIDE 1 ^ 

ARGUMENTS 

heading-text 

Specifies a heading. The doctype controls the font used to display the 
heading. By default, this tag has no heading. You may wish to create a 
heading using the <SYNTAX_DEFAULT_HEAD> tag. 

WIDE 

Specifies that the syntax statement can exceed the normal right margin of the 
text. If you are using doctype designs that indent the text body, a wide syntax 
example will extend into the left margin. 

related tags 

• <DISPLAY> 

• <SYNTAX_DEFAULT_HEAD> 

• The global < code-Example > tag 

• The global <FORMAT> tag 

restrictions 

You cannot use tab characters, index tags (such as the <x> and <Y> tags), 
or text element tags (such as <P> , <LIST> , or <NOTE> ) within this type of 
example. 

required 

<ENDSYNTAX> 

terminator 


DESCRIPTION 

The < SYNTAX > tag allows you to accurately describe language syntax. 
Languages can include programming languages, command languages, 
application defined languages, and so forth. This tag also separates the 
syntax example from the reihaining text, retains blank spaces and open lines, 
and labels the example (if you specified one) using a doctype-specific font 
different from the current text font. 
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<SYNTAX> 


EXAMPLE The following example shows how to use the < syntax > tag to describe a 

language's syntax. 

<P>The COPY command has the following syntax: 

<SYNTAX> 

COPY input-file output-file 

<ENDSYNTAX> 

This example may produce the following output. 

The COPY command has the following syntax: 

COPY input-file output-file 
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< SYNTAX 

_DEFAULT_HEAD> 

Creates a default heading for the <syntax> tag. 

FORMAT 

<SYNTAX_DEFAULT_HEAD> ([ heading-text 1 ^ 

(OFF / 

ARGUMENTS 

heading-text 

Specifies a heading to be used by all subsequent <SYNTAX> tags. The 
doctype controls the font used to display this heading. By default, the 
< SYNTAX > tag has no heading. 

OFF 

Disables any heading established by a previous use of the < SYNTAX- 
DEFAULT-HEAD > tag. 

related tags 

• <SYNTAX> 

restrictions 

None. 

required 

terminator 

None. 

DESCRIPTION 

Use the < syntax _default_head> tag to create a default heading for 
subsequent uses of the <SYNTAX> tag. Use the < syntax-DEFAULT-HEAD> 
tag to create the same default heading above each use of the <syntax> tag. 

You can disable all subsequent default headings by specifying the OFF 
argument to the < SYNTAX-DEFAULT-HEAD > tag. 

EXAMPLES 

The following example shows how the < syntax-DEFAULTJHEad > tag can be 
used to create a default heading for all subsequent < syntax > tags. 


Q <p> 

The COPY command has the following general syntax: 

<SYNTAX> 

COPY input-file output-file 

<ENDSYNTAX> 

<COMMENT>(Set up default headings for syntax statements....) 
<SYNTAX_DEFAULT_HEAD>(What the User Types) 

<P> 

An actual user would type the following: 

<SYNTAX> 

$ COPY MYFILE.TXT NEWFILE.TXT 
<ENDSYNTAX> 
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This example may produce the following output: 

The COPY command has the following general syntax; 

COPY input-file output-file 
An actual user would type the following: 

What the User Types 
$ COPY MYFILE.TXT NEWFILE.TXT 

The following example shows how to disable <syntax_default_head> tag 
for all subsequent <SYNTAX> tags. 

<COMMENT>(Set up default headings for syntax statements....) 

<SYNTAX_DEFAULT_HEAD>(What the User Types) 

<P> 

An actual user would type the following: 

<SYNTAX> 

$ COPY MYFILE.TXT NEWFILE.TXT 
<ENDSYNTAX> 

<C0MMENT>(Disable default headings for syntax statements....) 

<SYNTAX_DEFAULT_HEAD>(OFF) 

<P>The following is a semantic statement of the COPY operation. 

<SYNTAX> 

COPY [the existing file specification to] [the new file specification] 

<ENDSYNTAX> 

This example may produce the following output: 


An actual user would type the following: 

What the User Types 
$ COPY MYFILE.TXT NEWFILE.TXT 

The following is a semantic statement of the COPY operation. 
COPY [the existing file specification to] [the new file specification] 
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14.2 Tags Common to all Reference Templates 

The tags in this section are available in all SOFTWARE doctype reference 
templates. 

This section describes the tags you can use within any of the SOFTWARE 
doctype templates. You can use these tags after you use the template¬ 
enabling tags (such as <command_section> and < routine-section > ) 
and before you use the template-disabling tags (such as <ENDC0MMAND_ 
SECTION> and <ENDROUTINE_SECTION> . 

If you are unfamiliar with the use of the SOFTWARE doctype templates, refer 
to Chapter 8 for more information. 
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<DESCRIPTION> 

Begins a section of descriptive text providing detailed information on the 
current reference element. 

FORMAT 

< DESCRIPTION> [(alternate-heading)] 

ARGUMENTS 

alternate-heading 

Specifies a heading. The default heading is "Description." For information on 
how to modify the default headings for all subsequent < DESCRIPTION > tags, 
refer to the description of the <SET_TEMPLATE_HEADING> tag in this section. 

related tags 

• <OVERVIEW> 

• <SET_TEMPLATE_HEADING> 

• Any reference element tag: < COMMAND > , < ROUTINE > , < STATEMENT > , 

<FUNCTION> , or <SDML_TAG> 

restrictions 

Available only in the context of a reference section tag ( < COMMAND- 
SECTION> , <ROUTINE_SECTION> , <STATEMENT_SECTION> , or <TAG_ 
SECTION>). 

required 

terminator 

<ENDDESCRIPTION> 


DESCRIPTION The < DESCRIPTION > tag separates and labels detailed descriptive text 

concerning the current reference element (command, routine, and so on). 
This text can describe the following aspects of the reference element: 


• Suggested use 

• Special considerations 

• Use with other reference elements 

You should not use a <P> tag immediately after the <description> tag. 
The < DESCRIPTION > tag generates the initial open line so that you need only 
begin typing the first paragraph of text. 
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<DESCRIPTION> 


EXAMPLE The following example shows a sample use of the <overview> and 

< DESCRIPTION > tags within the context of the Command template. The 
Command template <command> tag and the global <format> and 
<PARAMDEFLIST> tags are included to make a more complete example. Note 
the inclusion of the reference element tag ( < command > ) forces a page break 
by default. 

<COMMAND_SECTION> 

<COMMAND>(SET TIME) 

<0VERVIEW> 

Resets the system time to the time specified as a parameter to this command. 

<ENDOVERVIEW> 

<F0RMAT> 

<FCMD>(SET TIME) <FPARMS>(time-specification) 

<ENDFORMAT> 

<PARAMDEFLIST> 

<PARAMITEM>(time-specification) 

<PARAMDEF> Specifies the time to which the system should be set. 

<ENDPARAMDEFLIST> 

<DESCRIPTION> 

The SET TIME command lets you reset the system clock on your VMS system. 

This command is generally used to make allowances for daylight savings time 
and other such events. 

<ENDDESCRIPTION> 

<ENDCOMMAND_SECTION> 

This example may produce the following output; 
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<DESCRIPTION> 

SET TIME 

Resets the system time to the time specified as a parameter to this 
command. 

FORMAT 

SET TIME time-specification 

PARAMETERS 

time-specification 

Specifies the time to which the system should be set. 

DESCRIPTION 

The SET TIME command lets you reset the system clock on your VMS 
system. This command is generally used to make allowances for daylight 
savings time and other such events. 
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<OVERVIEW> 


<OVERVIEW> 

Provides a summary description of a reference element. 

FORMAT 

<OVERVIEW> 

related tags 

• < DESCRIPTION > 

restrictions 

Can only be used in the context of a SOFTWARE reference template. 

required 

terminator 

<ENDOVERVIEW> 

DESCRIPTION 

The < OVERVIEW > tag lets you create a subsection that typically contains 
a brief definition of the reference element. Use the <DESCRlPTlON> tag 
to create a separate subsection that contains more detailed information 
to the user concerning the reference element. See the description of the 
<DESCRlPTlON> tag for more information. 

You do not need to use a <P> tag immediately after the < overview > tag. 
The <OVERVlEW> tag generates the initial open line; you need only type the 
first paragraph of text. 


EXAMPLE 

See the example in the discussion of the <DESCRlPTlON> tag in this section. 
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<SET_TEIVIPLATE_HEADING> 

Overrides the heading for all subsequent uses of a template tag. 


FORMAT <SET^TEMPLATE_HEADING> (element-keyword 

\ default-heading) 


ARGUMENTS element-keyword 

Is the standard reference template element whose default heading you wish 
to override. The reference element keywords, the related template tags, and 
the system default headings are listed in the following table. 


Keyword 

Template Tag 

Default Heading 

Command Template 

FORMAT 

<FORMAT> 

Format 

PARAMDEFLIST 

<PARAMDEFLIST> 

Parameters 

QUALDEFLIST 

<QUALDEFLIST> 

Qualifiers 

DESCRIPTION 

< DESCRIPTION > 

Description 

RETURN_VALUE 

<RETURN_VALUE> 

Return Value 

RESTRICTIONS 

<RESTRICTIONS> 

Restrictions 

PROMPTS 

<PROMPTS> 

Prompts 

Routine Template 

DESCRIPTION 

<DESCRIPTION> 

Description 

FORMAT 

<FORMAT> 

Format 

RSDEFLIST 

<RSDEFLIST> 

Return Values 

ARGDEFLIST 

<ARGDEFLIST> 

Arguments 

Tag Template 

All defaults established for the command template. 


ARGDEFLIST 

<ARGDEFLIST> 

Arguments 

PARAMDEFLIST 

<PARAMDEFLIST> 

Arguments 

RELATED_TAGS 

<RELATED_TAGS> 

Related Tags 

TERMINATOR 

<TERMINATING_TAG> 

Required Terminator 

Statement Template 

STATEMENT_FORMAT 

<STATEMENT_FORMAT> 

Format 


default-heading 

Is the heading you want to use for subsequent uses of the specified template 
tag. Enter the text in upper and lowercase letters. Remember that the 
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<SET_TEMPLATE_HEADING> 


headings defined for templates control the actual case to be output (all 
lowercase, all uppercase, or retained case). 


related tags • <set_template_para> 

• <SET_TEMPLATE_LIST> 

• <SET_TEMPLATE_TABLE> 


restrictions Valid only within the context of a reference template. 


required None. 

terminator 


EXAMPLE In the following example, the default heading text associated with the 

<PARAMDEFLIST> tag is redefined within the context of a tag template to 
have the heading "Function Types." 

<TAG_SECTION>(Functions) 

<SET_TEMPLATE_HEADING>(PARAMDEFLIST\Function Types) 

<PAMMDEFLIST> 

<PARAMITEM>(XYZ) 

<PARAMDEF> The XYZ argument returns the current software status code. 

<ENDPARAMDEFLIST> 


This example may produce the following output. 


FUNCTION 

TYPES 


XYZ 

The XYZ argument returns the current software status code. 
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ARGUMENTS list-tag-name 

Specifies the name of the tag that will introduce the list of items within the 
list template being defined. This tag name must be a valid tag name less than 
28 characters; it must not be the same as an existing SDML tag name. 

default-list-heading 

Specifies the default text heading to be output by the list template being 
defined. 

item-tag-name 

Specifies the name of the tag to be used to indicate individual items in the list 
being defined. This name must be a valid tag name. 

list-type 

Specifies the keyword that indicates the type of list the list being defined is 
based on. These keywords create the same list format as the same keywords 
used with the global <LIST> tag. These keywords are as follows: 

SIMPLE 

NUMBERED 

UNNUMBERED 

heading-level 

Specifies the template heading level to be associated with the tag. Valid 
values are 1 and 2, indicating a primary template heading or a secondary 
template heading. If this argument is not specified, the value defaults to 2, 
and the secondary template heading is used. 


related tags • <set_template_para> 

• <SET_TEMPLATE_HEADING> 

• <SET_TEMPLATE_TABLE> 

• The global <LIST> tag 


restrictions Can only be used within the context of a < COMMAND-SECTION> , 

<ROUTINE_SECTION> , <STATEMENT-SECTION > , Or <TAG-SECTION> tag. 
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<SET_TEMPLATE_LIST> 


required None. 

terminator 

EXAMPLES The following examples in this section assume that the following tag 

has been specified to enable the tags <shopping_list> , <sitem> , and 
<ENDSHOPPING_LIST> tags. 

<SET_TEMPLATE_LIST>(SHOPPING_LIST\Shopping List\SITEM\NUMBERED) 

The following example generates the default heading "Shopping List," and 
starts a numbered list. Each <SITEM> tag generates another numeric item in 
the list, as follows; 

Q <SHOPPING_LIST> 

<SITEM>one item 

<SITEM>second 

<ENDSHOPPING_LIST> 

This example may produce the following output: 


shopping list 1 one item 

2 second 

The following example shows how to override the default heading shopping 
list heading and produce the text "None." 

@ <SHOPPING_LIST>(BloomingdalesXNONE) 


This example may produce the following output: 


bloomingdales None. 
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<SET_TEMPLATE_PARA> 


<SET_TEMPLATE_PARA> 

Defines a set of template tags for setting the format of a paragraph of 
information. 

FORMAT 

<SET_TEMPLATE_PARA> (tag-name 

\ default-heading 
[ \ heading-level]) 

ARGUMENTS 

tag-name 

Specifies the user-defined name of the tag that begins the paragraph template 
and marks the beginning of the text in that paragraph. This tag name must 
be a valid tag name less than 28 characters; it must not be the same as an 
existing SDML tag name. 

default-heading 

Specifies a default heading to be associated with the paragraph template. This 
default heading can be overridden in the tag invocation, if needed. 

heading-level 

Specifies the template heading level to be associated with the tag. Valid 
values are 1 and 2, indicating a primary template heading or a secondary 
template heading. If this argument is not specified, it defaults to 2 and the 
secondary template heading is used. 

related tags 

• <SET_TEMPLATE_LIST> 

• <SET_TEMPLATE-TABLE > 

• <SET_TEMPLATE_HEADING> 

restrictions 

Valid only within the context of a reference template. 

required 

terminator 

None. 

EXAMPLES 

The following examples show how to use the <SET_template_para> tag. 

The <SET_TEMPLATE_PARA> tag in the following example creates the 
template tags <SIDE_effects> and <endside_effects> as the beginning 
and ending tags of a paragraph template with a default heading of "Side 
Effects:. " 

Note that this definition of the < SIDE-EFFECTS > tag is the one used in the 
following examples. 
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<SET_TEMPLATE_PARA> 

Q <SET_TEMPLATE_PARA>(SIDE_EFFECTS\Side Effects;) 


<SIDE_EFFECTS> 

Modifying the arguments to the PLACE command changes the positioning of the 
page number. 

<ENDSIDE_EFFECTS> 


This example may produce the following output. 


side effects: Modifying the arguments to the PLACE command changes the positioning of 

the page number. 

The following example shows how to specify the template tag <SIDE_ 
EFFECTS> with the alternate heading "Desired Effect=." 

g <SIDE_EFFECTS>(Desired Effect=) 

Modifying the arguments to the PLACE command changes the positioning of the 
page number. 

<ENDSIDE_EFFECTS> 

This example may produce the following output. 


desired effect= Modifying the arguments to the PLACE command changes the positioning of 

the page number. 

The following example shows how to specify the NONE keyword to the 
<SIDE_EFFECTS> template tag. 

0 <SIDE_EFFECTS>(NONE) 


This example may produce the following output. 


side effects: 


None. 


SOFTWARE Doctype Tag Reference 

<SET_TEMPLATE_TABLE> 


<SET^TEMPLATE_TABLE> 


Defines a set of template tags for setting information in two- or three- 
column lists. 


FORMAT <SET>_TEMPLATE_TABLE> rfa/?/e-fag-name 

\ default-table-heading 
\ table-row-tag-name 
\ column-count 
\ column-widths 
[ \ table-column-headings]) 


ARGUMENTS table-tag-name 

Specifies the user-defined name of the tag that begins the user-defined table. 
This tag name must be a valid tag name less than 28 characters; it must not 
be the same as an existing SDML tag name. 

default-table-heading 

Specifies a default heading to be output over the entire user-defined table. 
This heading may be overridden by an alternate heading specified as an 
argument to the < table-tag-name > tag. 

table-row-tag-name 

Specifies the name of the tag to be used to indicate individual table rows in 
the table being defined. This name must be a valid tag name. For example, if 
the table-row-tag-name argument is specified as SAMP_ROW, the individual 
table row tag will be <SAMP_ROW> . The user-defined tag created by this 
argument is similar to the global < TABLE _ROW> tag. 

column-count 

Specifies the number of columns in the user-defined table. The accepted 
arguments are as follows: 

• 2 — Specifies that the table is to have two columns. 

• 3 — Specifies that the table is to have three columns. 

column-widths 

Specifies the approximate widths of the table columns. The width of the 
last table column is determined by VAX DOCUMENT, so, if you specify a 
two-column table, you must specify only a single column width argument as 
shown in the following code example: 

<SET_TEMPLATE_TABLE>(KEYVALS\Keyword Values\KEYVAL\2\10\Keyword\Value) 
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<SET_TEMPLATE_TABLE> 


If you specify a three-column table, you must specify two column-width 
arguments as shown in the following code example: 

<SET_TEMPLATE_TABLE>(KEYVAL_TABLE\Keyword Ranges\KEYVAL\3\10\10\Keyword\High\Lower) 

table-column-headings 

Specifies the default headings for each column in the user-defined table. 

If you specify a two-column table, you can specify up to two heading 
arguments. If you specify a three-column table, you can specify up to three 
heading arguments. 


related tags • <set_template_list> 

• <SET_TEMPLATE_PARA> 


restrictions Valid only within the context of a reference template. 

required None. 

terminator 


DESCRIPTION Use the <SET_TEMPLATE_TABLE> tag to create your own user-defined set 

of tags for making a table with optional headings within a template. Tables 
created using this tag may have either two or three columns. This tag requires 
five arguments and accepts the optional table-column-headings argument. 

If you choose to omit the table-column-headings argument, then the table will 
not have any column headings and will not output rules within the table. 


EXAMPLES In the following example the < set_template-TABLE > tag sets the default 

heading to be "best songs," enables a two-column table, sets the text supplied 
to the two <45RPM> tags in the table, and then terminates the table. 

Q <SET_TEMPLATE_TABLE>(RECORDTABLE\Best Songs\45RPM\2\12\Performer\Song Title) 

<RECORDTABLE> 

<45RPM>(Sinatra\Strangers in the Night) 

<45RPM>(Moody Blues\Nights in White Satin) 

<ENDRECORDTABLE> 


This example may produce the following output. 


best songs 




Performer 

Song Title 


Sinatra 

Strangers in the Night 


Moody Blues 

Nights in White Satin 


The following example shows how to specify the NONE keyword to the 
<RECORDTABLE> tag. 
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<SET_TEMPLATE_TABLE> 


2 <REGORDTABLE>(NONE) 


This example may produce the following output. 


best songs None. 

The following example shows how to define a three column table with 
headings. The tags defined are the <opcodes> , <endopcodes> and 
<OPS> tags. 

g <SET_TEMPLATE_TABLE>(0PC0DES\codes\0PS\3\6\6\2-byte\3-byte\4-byte) 

<0PC0DES> 

<OPS>(abc\def\ghi) 

<END0PC0DES> 

This example may produce the following output. 


codes 





2-byte 

3-byte 

4-byte 

abc 

def 

ghi 
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14.3 The Command Reference Template Tags 

This section alphabetically describes the tags available in the Command 
template. Use these tags to create a command reference section. In 
most manuals, a command section is an encyclopedic reference section 
that describes each command the software system offers, along with the 
command's format, its arguments, and examples of its use. 
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<COMMAND> 


<COMMAND> 

Begins a new command description. 

FORMAT 

<COMMAND> (command-name 

[ \ informational-name]) 

ARGUMENTS 

command-name 

Names the command described in the section. 

informational-name 

Specifies an optional description of the command's function. 

related tags 

• < COMMAND-SECTION > 


• <SET-TEMPLATE-COMMAND> 

required 

terminator 

None. 

DESCRIPTION 

Use the <C0MMAND> tag to begin a description section for a single 
command in the context of the <commanD-SECTION> tag. This tag has 
the following default format: 


• Each <COMMAND> tag begins a new page of output. 

• Each output page carries a single running title, which is the current 
command name. 


• If the optional informational-name argument is used with the 

<C0MMAND> tag, this argument will be output after the command- 
name argument and the two arguments will be separated by an em dash 
(-). 

Use the <SET_TEMPLATE-COMMAND > tag to replace the <C0MMAND> tag 
with a tag whose name is more meaningful to you (for example, < internal _ 
COMMAND > ) or to change the default attributes of the < command > tag. 
See the description of the < SET-TEMPLATE-COMMAND > tag in this chapter 
for more information. 
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<COMMAND> 


EXAMPLES The following example shows a command section begun using the 

<COMMAND_SECTlON> tag. Within this command section the <COMMAND> 
tag is used to begin the command description for the OPEN command. 

Q <COMMAND_SECTION> 

<C0MMAND>(0PEN) 

<0VERVIEW> 


In the following example, the < COMMAND > tag has two arguments. 

The command name, CLOSE, appears at the beginning of the command 
description. The text specified in the second argument, "Close a File," is 
printed on the same line as the command name, separated by an em dash 
(-). 

<COMMAND_SECTION> 

<COMMAND>(CLOSE\Close a File) 
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<COMMAND_SECTION> 


<COMMAND_SECTION> 


Begins a command reference section, enables tags reserved for use in 
command sections, and sets paging attributes. 


FORMAT 


<COMMAND_SECTION> [([running-title] 

[ \ [number-prefix] 
[\NEWPAGE]])] 


ARGUMENTS running-title 

Specifies a top-level running heading to be used throughout the command 
section. If this argument is not specified, the running headings are determined 
as described in Section 8.4.2. 

number-prefix 

Specifies a character-string prefix to be used to construct page numbers 
(folios) and formal figure, table, and example numbers. If this argument is 
not specified, the page and formal element numbering are determined as 
described in Section 8.4.2. 

NEWPAGE 

Indicates that the command section should begin on a new page. This 
argument is only meaningful in two cases; 

• When you have previously entered the < SET_TEMPL ATE-COMMAND > tag 
with the NGNEWPAGE keyword to specify that each new command in 
this command section should not begin on a new page 

• When you want to place one or more pages of text between the end of a 
part page and the beginning of a command section 


related tags 




<SET_TEMPLATE_COMMAND> 

< SET-TEMPLATE-PARA > 

< SET-TEMPLATE -LIST > 
<SET_TEMPLATE_TABLE> . 
<SET_TEMPLATE-HEADING> 

< COMMAND > 

<OVERVIEW> 

<FORMAT> 

<FCMD> 

<FPARMS> 

<FPARM> 

<PARAMDEFLIST> 
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<COMMAND_SECTION> 


restrictions 

required 

terminator 

DESCRIPTION 


• <RESTRICTIONS> 

• < PROMPTS > 

• < DESCRIPTION > 

• <QUALDEFLIST> 

• <EXAMPLE_SEQUENCE> 


None. 


< ENDCOMMAND-SECTION > 


The <C0MMAND_SECTI0N> tag begins the command reference template. You 
can place a command section within a chapter or an appendix, or following a 
part page (that is, within a document section begun with the <part_page> 
tag). You code a command section in a chapter or an appendix in the same 
manner; command sections in parts are handled differently. 

If your command section follows a part page, and you include text between 
the part page and the command section, you should specify the NEWPAGE 
keyword as the third argument to the <command_section> tag. This 
causes the command section to begin on a new page. The following code 
fragment shows a command section that begins on a new page: 

<COMMAND_SECTION>(\CD\NEWPAGE) 

<HEAD1>(Command Format) 

When you use the < COMMAND-SECTION > tag within a chapter or an 
appendix, and you want to place text after the command section in 
that chapter or appendix, you must end the command section with the 
<ENDCOMMAND_SECTiON> tag and place the text after that tag. This text 
will by default begin on a new page of output. 

Specify the NONEWPAGE argument to the <ENDCOMMAND_SECTlON> tag 
if you do not want the text to begin on a new page of output. The following 
code fragment shows the end of a command section that specifies that the 
subsequent text not be placed on a new page: 

<ENDCOMMAND_SECTION>(NONEWPAGE) 

When the <endcommand_SECTION> tag is specified within the context of 
a chapter or appendix, it resets the default running titles to those in effect 
for the chapter or appendix, so the last page of the last command description 
in the command section may not carry the last command's name as the 
running heading. Instead it may carry the running title used by the chapter 
or appendix. 

The <COMMAND_SECTlON> tag can be used more than once in a document. 
By specifying arguments to that tag, and by using the <SET_TEMPLATE_ 
COMMAND > tag to specify additional attributes, you can tailor command 
sections to the specific requirements of your documentation. 
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<COMMAND_SECTION> 


EXAMPLES The following example shows how to begin a command section within a 

document part. 

Q <PART> 

<PART_PAGE> 

<TITLE>(Part III\Coimnand Dictionary) 

<ENDPART_PAGE>(RENUMBER) 

<COMMAND_SECTION>(Command Dictionary\CD) 

<SET_TEMPLATE_COMMAND>(DCL_COMMAND) 

<DCL_COMMAND>(GOTO) 

<0VERVIEW> 

Transfers control to a labeled statement in a command procedure. 

<ENDOVERVIEW 


<ENDCOMMAND_SECTION> 

The tags in the previous example perform the following functions: 

• The global <part> tag begins the part. 

• The global <part_page> tag creates a part page. 

• The global < title > tag is used in the context of the <part_page> tag 
to create a title on the part page. 

• The RENUMBER argument to the global <ENDPART_PAGE> tag specifies 
that the pages should be renumbered beginning with the part page. This 
causes the first page of text following the part page to be numbered page 
3 (Page 1 is the unnumbered page the part page title is placed oh, page 2 
is the back of page 1, and page 3 is the first numbered page after the part 
page). 

• The < COMMAND-SECTION > tag begins the command section and 
specifies the running title "Command Dictionary" as the running title 
for the command section. If the <SET_TEMPLATE_COMMAND> tag were 
used with the DOUBLERUNNINGHEADS argument, the title "Command 
Dictionary" would be used as the top running title. 

The < COMMAND-SECTION > tag also specifies that the prefix "CD" should 
be used to construct numbers for pages and for formal figures, tables, 
and examples within the command section (for example, CD-11, CD-32, 
Table CD-I, Example CD-2, and so on). 

• The < SET-TEMPLATE-COMMAND > tag specifies that all command 
descriptions in this command section will be identified using the 
tag <DCL_C0MMAND> rather than the default tag <command> . 

The <DCL_COMMAND> tag will have the default attributes of the 
< COMMAND > tag. 

The following example shows how you can create a command section in 
which each command description (begun with a < COMMAND > tag) is in a 
separate SDML file, and all these descriptions are included into a primary 
command description file. For example, the file MYCOMMANDS.SDML 
contains the following SDML tags: 

<INCLUDE>(CLOSE.SDML) 

<INCLUDE>(OPEN.SDML) 

<INCLUDE>(READ.SDML) 

<INCLUDE>(WRITE.SDML) 
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<COMMAND_SECTION> 


Each of the included files contains one command reference description 
begun with a < COMMAND > tag. For these files to process correctly, they 
must be preceded with the < COMMAND-SECTION > tag that enables the 
<COMMAND> tag. These files can have the necessary tags processed before 
them by specifying the /INCLUDE qualifier on the command line to include 
a startup definition file. 

<COMMAND_SECTION>(Command DictionaryXCD) 

<SET_TEMPLATE_COMMAND>(COMMAND\DOUBLERUNNINGHEADS) 

If this startup file were named COMMAND_DICT_STARTUP.SDML, it could 
be included using the DOCUMENT /INCLUDE qualifier as in the following 
example: 

$ DOCUMENT mycommands SOFT.REF LN03 /INCLUDE=COMMAND_DICT_STARTUP.SDML 

When each individual file in MYCOMMANDS.SDML is processed, the correct 
sequence of tags will be read in to begin the command section. 

You can process multiple files together by using the < INCLUDE > tag to 
include them into a single master file (such as MYCOMMANDS.SDML), or 
you can include them into a book build profile. 

You use the <ELEMENT> tags to include multiple files into a profile. 

For example, the book build profile file CDPRO.SDML could contain the 
following tags: 

<PR0FILE> 

<ELEMENT>(CLOSE.SDML) 

<ELEMENT>(OPEN.SDML) 

<ELEMENT>(READ.SDML) 

<ELEMENT>(WRITE.SDML) <C0MMENT>(contains <ENDCOMMAND_SECTION> tag) 

<ENDPROFILE> 

Note that the profile file should include the <ENDCOMMAND_SECTlON> tag 
in the appropriate file, so that the template will be terminated and the book 
build will process correctly. 
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<FCMD> 

<FCMD> 

Specifies a command or command keyword and an optional parameter list 
within the context of the <format> tag. 

FORMAT 

< FCM D> (command-keyword[ \ parameter-list]) 

ARGUMENTS 

command-keyword 

Specifies the command or command keyword. This text is output in the left 


portion of the format description. 

parameter-list 

Specifies the one or more parameters of the command or command keyword. 
This text is output to the right of the command in the format description with 
no space between the command-keyword and the parameter-list text. 

Parameters you specify using the parameter-list argument are output 
differently than parameters specified using the <FPARMS> tag. See the 
examples in this tag description for illustrations of these differences. 

related tags 

• <COMMAND_SECTION> 

• <FORMAT> 

• <FPARMS> 

• <FPARM> 

• <STATEMENT_FORMAT> 

restrictions 

• Valid only within the context of the < FORMAT > or < STATEMENT- 
FORMAT> tags. 

• If you do not provide a second argument to the <FCMD> tag, you should 
explicitly declare the absence of parameters by using the <fparms> tag 
as follows: 

<FCMD>(COMMAND-KEYWORD) <FPARMS>() 

If you do not specify a second argument to the <fcmd> tag and the 
<FPARMS> tag is not specified, VAX DOCUMENT issues a warning 
message. 

required 

terminator 

None. 
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<FCMD> 


DESCRIPTION Use the <FCMD> tag to label a command or command keyword within the 

context of the <format> tag. Use the parameter-list argument to this tag 
to create a list of one or more parameters that are formatted with no space 
between the command keyword and the parameter list. 

Use the <FPARMS> tag in conjunction with the <FCMD> tag to create 
a command format with the command keyword and the one or more 
parameters separated by a space. 

If the text of the parameter-list argument does not fit on a single line in the 
format section, the text formatter selects suitable line breaks based on the 
presence of spaces in the parameter-list text. Hyphenated text is not broken 
across lines. 


EXAMPLES The following examples show various uses of the <FCMD> tag. 

The following example specifies a command keyword with no parameters. 
Use the <FPARMS> after the <FCMD> to explicitly specify the absence of 
any parameters. 


<F0RMAT> 

<FCMD>(EXIT) <FPARMS>() 
<ENDFORMAT> 


This example may produce the following output. 


FORMAT EXIT 

The following example also specifies a command keyword with no 
parameters. This coding however specifies a null second argument to the 
<FCMD> tag rather than using the <fparms> tag to explicitly specify the 
absence of any parameters. 

0 <F0RMAT> 

<FCMD>(EXIT\ ) 

<ENDFORMAT> 


This example may produce the following output. 


FORMAT EXIT 

The following example specifies both the command-keyword and the 
parameter-list arguments to the <fcmd> tag. Note in the output sample 
how these two arguments are formatted together with no intervening spaces. 

g <F0RMAT> 

<FCMD>(F$ELEMENT\(element-number,delimiter,string)) 

<ENDFORMAT> 


This example may produce the following output. 


FORMAT F$ELEMENT (element-number,delimiter,string) 
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<FCMD> 


The following example specifies a command keyword with a list of two 
parameters using the <FCMD> and <FPARMS> tags. Note that coding the 
parameters using the <FPARMS> tag results in a space being output between 
the command keyword and the first parameter. 

2 <F0RMAT> 

<FCMD>(APPEND) <FPARMS>(input-file-spec output-file-spec) 

<ENDFORMAT> 

This example may produce the following output. 


FORMAT APPEND input-file-spec output-file-spec 

The following example specifies the <FCMD> tag using the global 
<KEYWORD> tag as part of the parameter-list argument text. Note how 
the global < keyword > tag alters the output. The output of this example is 
shown in Output Sample 5. 

H <F0RMAT> 

<FCMD>(SET PROTECTIONN[=code]<keyword>(/DEFAULT)) 

<ENDFORMAT> 


This example may produce the following output. 


FORMAT SET PROTECTION/=code7/DEFAULT 


14-103 



SOFTWARE Doctype Tag Reference 

<FORIVIAT> 


<FORMAT> 

Begins a section that highlights the syntax of a command, including its 
keywords and parameters. 

FORMAT 

<FORMAT> [(alternate-heading)] 

ARGUMENTS 

alternate-heading 

Specifies a heading to override the current default text heading for this use of 
the < FORMAT > tag. The default heading provided by VAX DOCUMENT is 
"Format." See the <SET-TEMPLATE-HEADING> tag description for information 
on modifying the default headings for all <FORMAT> tags. 

related tags 

• <COMMAND-SECTION> 

• <FCMD> 

• <FPARMS> 

• <FPARM> 

• <STATEMENT_FORMAT> 

required 

terminator 

<ENDFORMAT> 


DESCRIPTION The <FORMAT> tag creates sections of text that describe the format of a 

command, routine, or tag. It also enables the <FCMD> , <FPARMS> , and 
<FPARM> tags, which label specific portions of a format statement. 


The <FORMAT> tag is a global tag and is not restricted to command sections. 
The < FORMAT > tag enables additional tags in the context of the < ROUTINE- 
SECTlON> and <TAG_SECTiON> tags for specialized format descriptions. 
These additional tags are not available in the context of the < command- 
section > tag. 

You can use the <format> tag and the tags it enables in a variety of ways 
to represent the syntax of a command. The following list of code examples 
show some of the most regularly used format section tag combinations: 

• <FCMD>(command-keyword) <FPARMS>(parameter-list) 

This is the standard form, in which the command keyword and its 
parameter list are separated by a blank space. If the parameter list must 
be printed on more than one line, additional lines are aligned at the 
beginning of the parameter list. 

• <FCMD>(command-keyword\parameter-list) 

This form should be used for command functions in which a command 
and its parameters are not separated by blank spaces. 
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<FORMAT> 


<FCMD>(command-keyword) <FPARMS>(parameter-1) <FPARM>(parameter-2) 

This form is useful for commands with long parameter lists and with 
parameter names that are either long or need additional information. 


EXAMPLES The following example shows how to use the <fcmd> and <fparms> tags 

to present a command format. 

g <F0RMAT> 

<FCMD>(CANCEL BREAK) <FPARMS>([address-expression[,<hellipsis>]]) 

<ENDFORMAT> 


This example may produce the following output. 


FORMAT CANCEL BREAK [address-expressionf, ... 77 

The following example uses multiple formats for a single command, with a 
special heading for each format. 

2 <F0RMAT>(Deleting all Logical Names) 

<FCMD>(ASN) <FPARMS>(= logical-name [keywords]) 

<ENDFORMAT> 

<F0RMAT>(Format for Deletion) 

<FCMD>(ASN) <FPARMS>(=) 

<ENDFORMAT> 

This example may produce the following output. 


DELETING ASN = logical-name [keywords] 

ALL LOGICAL 
NAMES 


FORMAT FOR ASN = 
DELETION 
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<FPARM> 


<FPARM> 

Adds a single parameter line to a list of parameters in a command syntax 
format section. 

FORMAT 

<FPARM> (parameter-name) 

ARGUMENTS 

parameter-name 

Specifies a single-line item to be formatted in a format parameter list. 

related tags 

• <COMMAND_SECTION> 

• < FORMAT > 

• <FCMD> 

• <FPARMS> 

• <STATEMENT_FORMAT> 

restrictions 

Can only be specified following an <FCMD> tag and <fparms> tag 
sequence in a format section. 

required 

terminator 

None. 

EXAMPLE 

The following example shows a sample use of the <FPARM> tag. 


<F0RMAT> 

<fcmd>(SET TERMINAL) <fparms>([device-name[:]]) 
<fparm>(/DEVICE_TYPE=<list>(stacked\braces) 

<le><keyword>(UNKNOWN) 

<le><keyword>(LA34) 

<le><keyword>(VTIOO) 

<le><keyword>(PRO_SERIES)<endli8t>) 
<fparm>(<list>(stackedXbrackets) 

<le>/LINE_EDITING 

<le>/NOLINE_EDITING<endlist>) 

<fparm>(<list>(stackedXbrackets) 

<le>/PASSALL 

<le>/NOPASSALL<endlist>) 

<ENDFORMAT> ' 
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<FPARM> 


This example may produce the following output: 


FORMAT SET TERMINAL [device-name[:]] 

/DEVICE-TYPE= 

( UNKNOWN 
LA34 
VT100 

I PRO-SERIES 

/LINE-EDITING 

/NOLINE-EDITING 

'/PASSALL 

/NOPASSALL 
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<FPARMS> 


<FPARMS> 

Specifies the parameters to a command or keyword. 

FORMAT 

<FPARI\/IS> (parameter-list) 

ARGUMENTS 

parameter-list 

Specifies one or more parameters to a command or keyword. 

You can also use this command to explicitly declare that a command or 
keyword marked with the <FCMD> tag has no parameters, as shown in this 
example. 

<FCMD>(EXIT) <FPARMS>() 

Parameters you specify using the <FPARMS> tag are printed differently than 
parameters specified in the parameter-list argument to the <FCMD> tag. See 
the examples in this tag description for illustrations of the different output 
styles. 

related tags 

• <COMMAND_SECTION> 

• <FORMAT> 

• <FCMD> 

• <FPARM> 

• <STATEMENT_FORMAT> 

restrictions 

The <FPARMS> tag should be used with the <FCMD> tag in the context of 
the <FORMAT> tag. 

required 

None. 

terminator 


DESCRIPTION 

The <FPARMS> tag identifies the parameters to a command or keyword. The 
command or keyword is identified with the tag <FCMD> . These tags should 
only be used in a format section. That is, they should only occur following 
the < FORMAT > tag and before the <ENDFORMAT> . 

When you use this tag to define a parameter list that contains multiple words 
or text strings, you should include blank spaces between the words and text 
strings (including punctuation) according to the syntax rules of the command 
you are describing. 

If the text of the parameter-list argument will not fit on a single line in the 
format section, the text formatter selects suitable line breaks based on the 
presence of spaces in the parameter-list text. Hyphenated text is not broken 
across lines. 
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<PROMPT> 

Identifies a prompt that appears on a separate line from other prompts, 
and any parameters associated with that prompt. 

FORMAT 

<PROMPT> (prompt-text \ related-parameter 
[ \ prompt-width]} 

ARGUMENTS 

prompt-text 

Specifies the prompt being described. All spacing and capitalization is 
retained as entered in the output. 

related-parameter 

Specifies any parameters related to the prompt. 

prompt-width 

Specifies the pica width of the column in which the prompt text is formatted. 
This value must be specified as a positive integer. 

By default, the width of the column is five picas, including any space between 
the prompt-text and the related-parameter columns (there are six picas to an 
inch). If the prompt text and the related parameter text are formatted too 
closely together, you should increase this value. 

related tags 

• < PROMPTS > 

restrictions 

Valid only within the context of the < PROMPTS > tag. 

required 

terminator 

None. 


EXAMPLES The following example shows how to use the <prompt> tag to specify two 

command prompts. 


Q <PR0MPTS> 

<PR0MPT>(Device:\equivalence-name[,,,]) 
<PR0MPT>(Log name:\logical-name:) 
<ENDPROMPTS> 


This example may produce the following output: 


prompts Device: equivalence-name[,„] 

Log name: logical-name: 

The following example shows how to specify the prompts for a SET 
PASSWORD command. In this example, the prompt-width argument extends 
the width of the prompt text to seven picas. 
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<PROMPT> 


g <PR0MPTS> 

<PR0MPT>(Old password;\old-password\7) 

<PR0MPT>(New password:\new-password\7) 

<PR0MPT>(Verification;\new-password\7) 

<ENDPROMPTS> 

This example may produce the following output: 

prompts Old password: old-password 

New password: new-password 
Verification: new-password 
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<PROMPTS> 



EXAMPLES The following example illustrates a command with a single prompt. 

Q <PR0MPTS>(Prompt) 

<PR0MPT>(File:\filespec) 

<ENDPROMPTS> 

This example may produce the following output. 


prompt File: filespec 

The following example illustrates a command with no prompts. Note that the 
terminator, <endprompts> , is not specified. 

2 <PR0MPTS>(N0NE) 

This example may produce the following output. 


prompts None. 
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<RESTRICTIONS> 



EXAMPLES The following example shows how to set a simple paragraph of text for the 

restrictions section using the <RESTRICTI0NS> tag. 


y <RESTRICTIONS> 

You must have OPER privilege to execute this command. 

<ENDRESTRICTIONS> 

This example may produce the following output, 
restrictions You must have OPER privilege to execute this command. 
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<RESTRICTIONS> 


The following example uses the NONE keyword to indicate that there are no 
restrictions on the use of the command. 


g <RESTRICTIONS>(NONE) 

This example may produce the following output. 


restrictions None. 

The following example illustrates a set of restrictions in a list. Note the use of 
the LIST argument and how it enables the <ritem> tag. 

g <RESTRICTIONS>(LIST) 

<RITEM>When you use /EDIT, no other qualifiers are allowed. 

<RITEM>The /ALL qualifier requires OPER privileges. 

<ENDRESTRICTIONS> 


This example may produce the following output. 


restrictions 


• When you use /EDIT, no other qualifiers are allowed. 

• The /ALL qualifier requires OPER privileges. 
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<RETURN 

-VALUE> 

Labels a character string return value. 

FORMAT 

<RETURN_VALUE> [(alternate-heading)] 

ARGUMENTS 

alternate-heading 

Specifies a heading to override the current default text heading for this 
use of the <return-VALUE > tag. The default heading provided by 

VAX DOCUMENT is "Return Value." See the reference description of the 
<SET_TEMPLATE_HEADING> tag for information on how to modify the default 
headings for all <return_value> tags. 

related tags 

None. 

restrictions 

Can only be used in the context of the Command template. 

required 

terminator 

< ENDRETURN -VALUE > 

EXAMPLE 

<RETURN_VALUE> 

abc-def-ghi 

The following example shows how to use the <RETURN-VALUE> tag. 

<ENDRETURN_VALUE> 

This example may produce the following output. 

return value 

abc-def-ghi 
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<RITEM> 

<RITEM> 

Labels an item in a list of restrictions. 

FORMAT 

<RITEM> 

related tags 

• <RESTRICTIONS> 

restrictions 

Can only be used in the context of the <RESTRiCTiONS> tag. 

required 

terminator 

None. 


EXAMPLE The following example shows how to create a list of restrictions. Note how 

the < RESTRICTIONS > tag is specified with the LIST keyword argument. Note 
how this enables the <RITEM> tag. 


<RESTRICTIONS>(LIST) 

<RITEM>You must not unplug this appliance while it is operating. 

<RITEM>This appliance should not be immersed in water. 

<ENDRESTRICTIONS> 

This example may produce the following output. 

r6Strictions • You must not unplug this appliance while it is operating. 

• This appliance should not be immersed in water. 
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<SET_TEMPLATE_COMMAND> 


<SET_TEMPLATE_COMMAND> 

Defines a new tag with the same function as the <command> tag, and 
changes the format of command descriptions produced using the new tag. 


FORMAT <SET_TEMPLATE_COMMAND> (tag-name 

[ \ attribute] 
[ \ attribute] 
[ \ attribute]) 


ARGUMENTS tag-name 

Specifies the name of the template tag being defined. This tag name must 
be a valid tag name less than 31 characters; it must not be the same as an 
existing SDML tag name other than "COMMAND" (which is the default tag 
name). 

attribute 

Specifies one of three keywords that can be used to override the default 
attributes for the < COMMAND > tag. 

• NONEWPAGE 

Prevents command descriptions from starting on new pages. By default, 
each tag-name template tag begins a command description on a new page. 

• DOUBLERUNNINGHEADS 

Enables two running titles at the top of every page. The top running title 
will be set by the <COMMAND_SECTlON> tag or by the heading of the 
most recent <chapter> or <appendix> tag. By default, if a doctype 
does not call for running top titles, only the current command name is 
placed at the top of each page. 

• STACK 

Stacks multiple arguments to the tag-name tag. By default, when multiple 
arguments are specified, the second and third arguments are assumed to 
be optional descriptive information, and are output on the same line as 
the command name. 


related tags • <command_section> 

• <COMMAND> 


restrictions Available only within the context of the < COMMAND-SECTION > tag. 


required None. 

terminator 
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<SET_TEMPLATE_COMMAND> 


DESCRIPTION The < SET-TEMPLATE-COMMAND > tag lets you create a tag with the functions 

of the <C0MMAND> tag, but with a name that is more meaningful to you. 

This tag also lets you change the default attributes associated with the 
< COMMAND > tag, or give your new tag different attributes than the 
<COMMAND> tag. 


EXAMPLES 

Q <COMMAND_SECTION>(FDL Commands\\NEWPAGE) 

<SET_TEMPLATE_COMMAND>(FDL_COMMAND\NONEWPAGE\STACK\DOUBLERUNNINGHEADS) 

<FDL_COMMAND>(STARTUP_FILE\STF) 

These tags begin a command section and define the tag <fdl-COMMAND > 

as the command descriptor tag. The attributes set are as follows: 

• Commands do not start on new pages. 

• When two arguments are specified to the tag <FDL-COMMAND > , the 
arguments are stacked. That is, the second argument is printed under the 
first. 

• Each page carries a two-line running title. The top line is "FDL 
Commands" and the second line is the name of the command description 
that is current at the top of the page. 

Note that this command sequence is most appropriate for a series of 

command descriptions that occur within a chapter. 


<PART> 

<PART_PAGE> 

<TITLE>(PART II\XYZ Conunands) 

<ENDPART_PAGE>(RENUMBER) 

<COMMAND_SECTION>(XYZ Commands\XYZ) 

<SET_TEMPLATE_COMMAND>(XYZ_COMMAND) 

These tags begin a document part in which only command descriptions occur, 
The RENUMBER argument on the <ENDPART-PAGE> tag specifies that the 
first page of the new Part (the part page itself) should be numbered page 1. 
The < COMMAND-SECTION > tag sets the folio prefix to XYZ; that is, pages 
will be numbered XYZ-3, XYZ-4, and so on. 

No attributes are specified for the command descriptions produced by 
<XYZ-COMMAND> . These commands will have default attributes. The 
first command will start on a new page. Since RENUMBER was specified on 
<ENDPART-PAGE> , the first command will be on the page numbered XYZ-3. 
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<SET_TEMPLATE_SUBCOMMAND> 


<SET_TEMPLATE_SUBCOMMAND> 

Changes the name of the <subcommand> tag to the name you specify, 
and specifies formatting attributes for the new tag. 

FORMAT <SET_TEMPLATE_SUBCOMMAND>(fag-name 

[\NONEWPAGE]) 

ARGUMENTS 

tag-name 

Specifies the name of the template tag being defined. This tag name must 
be a valid tag name less than 31 characters; it must not be the same as an 
existing SDML tag name other than "SUBCOMMAND" (which is the default 
tag name). 

NONEWPAGE 

Specifies that the corresponding subcommand reference descriptions should 
not start on a new page of output. 

related tags 

• <SUBCOMMAND> 

• <SUBCOMMAND_SECTION> 

restrictions 

This tag is only valid within the context of the <COMMAND_SECTlON> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <SET_TEMPLATE_SUBC0MMAND> tag lets you change the name of the 
< SUBCOMMAND > tag. This helps you make the coding of your source files 
more meaningful. 

EXAMPLE 

The following example shows how to create a subcommand section within 
a command section. The subcommand section is used to describe keywords 
associated with the command. 


<SUBCOMMAND_SECTION> (Qualifiers) 
<SET_TEMPLATE_SUBCOMMAND>(qUALIFIER) 
<QUALIFIER>(/OUTPUT) 

<overview> 
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<SET_TEMPLATE_SUBCOMMAND> 


The following default attributes are set in the previous example: 

1 Each subcommand description that begins with the < QUALIFIER > tag 
starts on a new page of output. 

2 Each page carries a two-line running title. The top line is "Qualifiers" and 
the second line is the name of the subcommand description that is current 
at the top of the page. 


14-120 



SOFTWARE Doctype Tag Reference 

<SUBCOMMAND> 


<SUBCOMMAND> 

Begins a new subcommand description. 

FORMAT 

<SUBCOMMAND> (subcommand-name) 

ARGUMENTS 

subcommand-name 

Names the command described in the subcommand section. 

related tags 

• < SET-TEMPLATE-SUBCOMMAND > 

• <SUBCOMMAND_SECTION> 

required 

terminator 

None. 

DESCRIPTION 

The <suBCOMMAND> tag begins a subcommand description section. 
Subcommand sections these format defaults: 

• Each <SUBCOMMAND> tag begins a new page of output. 

• The subcommand name appears as the single running title on each page. 

To change the name of the <subcommand> tag, or to change its default 
attributes see the description of the <set-TEMPLATE_subcommand> tag. 


EXAMPLES 


<SUBCOMMAND_SECTION> 

<SUBCOMMAND>(OPEN) 

<0VERVIEW> 


In this example, the < SUBCOMMAND-SECTION > tag enables the tags for a 
subcommand description. The description of the subcommand OPEN will, by 
default, have the following attributes: 

1 The subcommand description begins on a new page. 

2 If the subcommand carries for more than a page, the name "OPEN" is 
carried as a running top title on each page. 
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<SUBCOMMAND> 


<SUBCOMMAND_SECTION>(File System Subcommands) 
<SUBCOMMAND>(CLOSE) 


In this example the <SUBC0MMAND_SECTI0N> tag starts a subcommand 
section and gives it the title "File System Subcommands." In this command 
section, until the <ENDSUBCOMMAND_SECTiON> tag, each page of output 
carries this title at the top of page, with the name of the current subcommand 
just below it. 
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<SUBCOMMAND_SECTION> 


<SUBCOMMAND_SECTION> 


Begins a subcommand reference section within the command section; use 
this tag to begin a reference section for subordinate commands. 

FORMAT 

<SUBCOMMAND_SECTION>/(mnn/nfli-t/f/e 

[\NEWPAGE ])] 

ARGUMENTS 

running-title 

Specifies text to be placed at the top of each page of the subcommand section. 

NEWPAGE 

Specifies that the subcommand section is to start on a new page. Note that 
this argument is required only if subcommands themselves do not start on 
new pages, or if you use the < SUBCOMMAND-SECTION-HEAD > tag to provide 
introductory text for the subcommand section. 

related tags 

• < COMMAND-SECTION > 

• <SUBCOMMAND> 

• <SET-TEMPLATE-SUBCOMMAND> 

• < SUBCOMMAND-SECTION-HEAD > 

restrictions 

This tag is only valid within the context of the < COMMAND-SECTION > tag. 

required 

terminator 

<ENDSUBCOMMAND-SECTION> 

DESCRIPTION 

The < SUBCOMMAND-SECTION > tag allows you group descriptions of 
commands that are subordinate to a specific command description. 


EXAMPLES 


<SUBCOMMAND_SECTION>(File System Subcommands) 
<SUBCOMMAND>(CLOSE) 

<overview> 


This example illustrates a subcommand section within a command section. 
The subcommand section is used to describe subordinate commands. 
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<SUBCOMMAND_SECT[ON_HEAD> 


< SU BCOM M AN D_S ECTI0 N _H E AD > 

Specifies the heading for text that precedes a subcommand section. 

FORMAT 

<SUBCOMMAND_SECTION_HEAD> (heading) 

ARGUMENTS 

heading 

Specifies a heading that precedes introductory text for the subcommand 
section. 

related tags 

• <SUBCOMMAND> 

• <SET_TEMPLATE_SUBCOMMAND> 

restrictions 

This tag is only valid within the context of the <subcommand_section> 
tag. 

required 

terminator 

None. 

DESCRIPTION 

The <SUBCOMMAND_SECTlON_HEAD> tag lets you provide introductory text 
for a section of descriptions of commands that are subordinate to a specific 
command description. 

EXAMPLE 

This example illustrates a subcommand section within a command section. 
The subcommand section is used to describe subordinate commands. 


<SUBCOMMAND_SECTION>(File System SubcommandsXNEWPAGE) 
<SUBCOMMAND_SECTION_HEAD>(Subcommand Descriptions) 

<p>This section provides information about each of the subcommands 
you can enter while you are conversing with the file subsystem. 
<SUBCOMMAND>(CLOSE) 

<overview> 
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14.4 The Routine Reference Template Tags 

This section alphabetically describes the tags available in the Routine 
template. Use these tags to create a routine reference section. In most 
manuals, a routine reference section is an encyclopedic reference section that 
describes each routine the software system offers, the routine's format, its 
arguments, and examples of its use. 
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<ARGTEXT> 


<ARGTEXT> 


Labels definition text in an argument definition list which replaces the 
information contained in a pair of <argitem> and <argdef> tags. 

FORMAT 

<ARGTEXT> 

related tags 

• <ARGDEFLIST> 

• <ARGDEF> 

• <ARGITEM> 

restrictions 

Valid only within the context of the <ARGDEFLIST> tag within the Routine 
template. 

required 

terminator 

<ENDARGTEXT> 

DESCRIPTION 

The <ARGTEXT> tag labels definition text in an argument definition list which 
replaces the information contained in a pair of <argitem> and <argdef> 
tags. This tag is most useful when the arguments to be described are already 
listed elsewhere in the reference documentation. 

EXAMPLE 

The following example shows how to use the <ARGTEXT> tag to replace a 
pair of <ARGDEF> and <argitem> tags. Note that this tag is restricted to 
argument definition lists used in the context of the Routine template. 

<routine_section> 


<argdeflist> 

<argtext> 

The arguments to the SYS$N0NE routine are identical to those used 

by the SYSiNULL routine. See the description of the SYS$NULL routine for 

more information on these arguments. 

<endargtext> 

<endargdeflist> 

<endroutine_section> 

This example may produce the following output. 

ARGUMENTS 

The arguments to the SYS$NONE routine are identical to those used by the 
SYS$NULL routine. See the description of the SYS$NULL routine for more 
information on these arguments. 
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<FARG> 



ARG U M E NTS argument-name 

Specifies a single-line item to be formatted for a routine's argument list. 


related tags • <routine_section> 

• <FARGS> 

• <FFUNC> 

• <FORMAT> 

• <FRTN> 


restrictions Valid only within the context of the <FORMAT> tag following an <FRTN> 

tag and an <fargs> tag sequence. 

required None. 

terminator 

EXAMPLE The following example shows how to use the <FARG> tag to format a 

routine that allows a number of keyword arguments, each of which may 
specify several values. 

<F0RMAT> 

<frtn>($FAB)<fargs>(ALQ = allocation-quantity,) 

<farg>(BKS = bucket-size,) 

<farg>(DEQ = extension-quantity,) 

<farg>(DNA = default-filespec-address,) 

<farg>(FNA = filespec-string-address,) 

<farg>(0RG = <list>(stacked\braces) 

<le>REL 

<le>SEQ 

<le>IDX<endlist>,) 

<farg>(RAT = <list>(stacked\braces) 

<le>CR 

<le><BLK FTN> 

<le>PRN<endlist>,) 

<farg>(RTV = window-size,) 

<farg>(SHR = <list>(stacked) 

<le><PUT GET DEL 

<le>UPD NIL MSE UPI><endlist>,) 

<farg>(XAB = xab-address) 

<ENDFORMAT> 

This example may produce the following output. 
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<FARG> 


FORMAT 

SAMPLE 


$FAB 


ALQ = allocation-quantity, 
BKS = bucket-size. 


DEQ = extension-quantity, 

DNA = default-filespec-address, 
FNA = filespec-string-address. 


ORG = SEQ 


I IDX ) 

' CR 

rat = I cbLK ftn> 

I PRN 

RTV = window-size, 

SHR = I get del \ 

I UPD NIL MSE UPI> I ' 
XAB = xab-address 
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<FARGS> 


<FARGS> 

Provides the argument portion of a routine syntax statement within the 
context of the <format> tag. 

FORMAT 

<FARGS> (argument-list[ \ STACK]) 

ARGUMENTS 

argument-list 

Lists the routine arguments. If there are no arguments, specify the argument 
list as null as follows: 

<FRTN>($HIBER) <FARGS>() 

Parameters specified in this argument differ on output from parameters 
specified using the second argument to the <FRTN> tag. For distinctions 
between these output differences, see the "Examples" section in the <FRTN> 
tag description. 

STACK 

Specifies that the routine's argument list should not be formatted on the same 
line as the routine name, but placed on the next line. 

This keyword is required only for long routine names in certain doctypes. See 
if the output looks wrong before you use this argument. 

related tags 

• <FRTN> 

• <FARG> 

• <FFUNC> 

restrictions 

The <FARGS> tag should be used with the <frtn> tag in the context of the 
<FORMAT> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <FARGS> tag formats the argument portion of a routine in the context 
of the < FORMAT > tag. 

When you use this tag to contain an argument list with multiple words or 
text strings, enter blank spaces between the words and text strings (including 
punctuation) according to the syntax rule of the routine you are describing. If 
the parameter-list argument text does not fit on one line, suitable line breaks 
are chosen based on the presence of spaces. Hyphenated text is not broken 
across lines. 

You can select explicit line breaks in an argument list by using the <FARG> 
tag. 
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FORMAT SMG$BEGIN_PASTEBOARD^UPDATE 

pasteboard-id 
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<FFUNC> 

<FFUNC> 

Labels a routine that is a function within the context of a <format> tag 
section. 

FORMAT 

<FFUNC> ([return-val \ ]f unction-name 
\ argument-list) 

ARGUMENTS 

return-val 

Specifies a variable name where the function returns a value. 

function-name 

Specifies the name of the function. 

argument-list 

Specifies the function's argument list. 

related tags 

• <FORMAT> 

• <FRTN> 

• <FARGS> 

• <FARG> 

restrictions 

May only be specified within the context of a <FORMAT> tag section. 

required 

terminator 

None. 

DESCRIPTION 

The <FFUNC> tag is used within the context of the < FORMAT > tag to output 
the syntax of a function. This tag lets you create a syntax which includes the 
following: 


• The name of the function 

• The return value of the function 

• Any arguments that the function may require 






FORMAT status^AAA$CODE(arg-one , arg-two ,arg-three 

.arg-four ,arg-five ,arg-six 
,arg-seven} 
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<FORMAT> 


<FORIVIAT> 


Begins a section that illustrates the syntax of a routine including keywords 
and arguments. 

FORMAT 

<FORMAT> [(alternate-heading)] 

ARGUMENTS 

alternate-heading 

Specifies a heading to override the current default text heading for this use 
of the <FORMAT> tag. The default heading provided by VAX DOCUMENT 
is "Format." See the reference description of the <SET-TEMPLATE-HEADING> 
tag for information on how to modify the default headings for all < FORMAT > 
tags. 

related tags 

• <FRTN> 

• <FARGS> 

• <FARG> 

• <FFUNC> 

required 

terminator 

<ENDFORMAT> 


DESCRIPTION The <FORMAT> tag creates sections of text that describe the format of a 

command, routine, or tag. This tag is a global tag and is not restricted to 
routine sections. However in the context of the < ROUTINE-SECTION > and 
< TAG-SECTION > tags, the < FORMAT > tag enables certain additional tags 
for specialized format descriptions. These additional tags are not available 
outside of the context of routine or tag sections. 

The global <format> tag enables the <fcmd> , <fparms> , and 
<FPARM> , which label specific portions of a format statement. In a routine 
section, the <format> tag also enables the tags <frtn> , <fargs> , 
<FARG> , and <FFUNC> . 

You can use the <format> tag and the tags it enables in a variety of ways 
to show the syntax of a routine. The following list of code examples show 
some of the most regularly used format section tag combinations: 

• <FRTN>(routine-keyword) <FARGS>(argument-list) 

This is the standard form, in which the routine keyword and its argument 
list are separated by a blank space. If the argument list, on output, is 
more than a single line, additional lines will be aligned at the beginning 
of the argument list. 
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<FORMAT> 


• <FRTN>(routine-keyword\argument-list) 

This form should be used for routine functions, in which a routine and its 
arguments are not separated by blank spaces. 

• <FRTN>(return-val\routine-keyword\argument-list) 

This form provides three distinct elements for a routine description: the 
return value, the function name (shown here as the "routine-keyword"), 
and the argument list. 

• <FRTN>(keyword-part) <FARGS>(argument-1) <FARG>(argument-2) 

This form is useful for routines with long argument lists and in which 
the argument names themselves are either long or need additional 
information. 

• <FFUNC>(routine-keyword\argument-list) 

This form does not separate the routine name from its argument list and 
so is appropriate for function routines. 

• <FFUNC>(return-val\routine-keyword\argument-list) 

This form provides three distinct values (the return value, the function 
name, and the argument list). 


EXAMPLES The following example shows how to use the <FRTN> and <FARGS> tags 

in the context of the < FORMAT > tag to format a routine name and argument 
list. In this example, the argument list is null. 

Q <F0RMAT> 

<FRTN>(SYS$HIBER) <FARGS>() 

<ENDFORMAT> 


The following example shows how to use multiple <FFUNC> tags within a 
format section. 


<F0RMAT> 

<ffunc>(MTH$SQRT\(x)) 
<ffunc>(MTH$DSQRT\(x)) 
<f f uiic> (MTH$GSQRT\ (x)) 
<ffunc>(MTH$HSQRT\(x)) 
<ENDFORMAT> 
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<FRTN> 


<FRTN> 

Specifies the routine-keyword portion of a routine syntax statement within 
the context of the <format> tag. 

FORMAT 

< FRTN > ([return-val \ Jroutine-keyword 
[ \ argument-list]) 

ARGUMENTS 

return-val 

Indicates that the routine's format includes the descriptive name of a variable. 
The routine returns a value to this argument. Note that this argument is 
optional. 

routine-keyword 

Specifies the name of the first part of the format statement; typically this is 
the routine name or an operating system keyword. 

argument-list 

Specifies the arguments to be listed in the format statement. 

Parameters specified in this argument are different from parameters specified 
using the <FARGS> tag. The "Examples" section in this description shows 
the differences. 

related tags 

• <FARGS> 

• <FARG> 

• <FFUNC> 

restrictions 

If you specify <FRTN> with a null second argument, it is recommended that 
you explicitly declare the absence of arguments using the <FARGS> tag as 
follows: 

<FRTN>(KEYWORD-PART) <FARGS>0 

If you do not specify a second argument, and if the <fargs> tag is not 
specified, VAX DOCUMENT issues a warning message. 

required 

terminator 

None. 
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<FRTN> 



FORMAT sfat6ys=AAA$CODE arg-one , arg-two ,arg-three 

,arg-four ,arg-five ,arg-six 
.arg-seven 
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<RETTEXT> 

<RETTEXT> 

Provides general information about the attributes of the value returned by 
the routine. 

FORMAT 

<RETTEXT> 

required 

terminator 

<ENDRETTEXT> 

restrictions 

This tag is valid only following the <RETURNS> tag. 

DESCRIPTION 

The <RETTEXT> tag lets you place one or more paragraphs of 
information after some usage of the <RETURNS> tag. This information 
begins immediately after the <RETTEXT> tag and continues until the 
<ENDRETTEXT> tag is encountered. 

This tag is typically used when the arguments passed to the < RETURNS > tag 
are not sufficiently descriptive. 


EXAMPLE 

See the example in the discussion of the <RETURNS> tag. 
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<RETURNS> 


<RETURNS> 


Provides information about the value returned by a routine. 


FORMAT <RETURNS> (usage-information 

\data-type \ access 
\ mechanism[\ optional-info]) 

<RETURNS> (HEADONLY) 


ARGUMENTS usage-information 

Specifies a keyword indicating the category of data to which the return 
value belongs. These keywords are system dependent and are specified by 
agreed-upon conventions. 

data-type 

Indicates the data type of the return value, for example, longword, byte, 

G—floating, and so on. 

access 

Indicates the access applied to the return value, for example, read-only, 
write-only, and so on. 

mechanism 

Specifies the mechanism by which the return value is passed; for example, by 
descriptor, by reference, or by value. 

optionai-info 

Specifies additional information which may be appended to the mechanism 
argument output. 

HEADONLY 

Indicates that specific usage information is not relevant, and that text will be 
provided to describe the return attributes of the routine. 


related tags • <rettext> 


required None. 

terminator 


DESCRIPTION The returns section of the Routine reference template and its specialized 

argument list are used only by convention for those documenting callable 
routines. 
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<RETURNS> 


EXAMPLES The following example shows how to specify multiple arguments to the 

< RETURNS > tag. 

Q <RETURNS>(floating_point\ 

F_Floating, D_Floating, or G_Floating\write only\by value in RO) 

This example may produce the following output. 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


fioating—point 

F_Floating, D_Floating, or G—Floating 
write only 
by value in RO 


The following example shows a use of the READONLY argument. The return 
value from a routine or set of related routines may be too complex to express 
using the conventional arguments. 

<RETURNS>(headonly) 

<RETTEXT>The square roots of F_Floating, D_Floating, and G_Floating 
input parameters are returned by immediate value in RO and Rl. The 
square root of an H_Floating parameter is returned by reference 
in the output parameter <VARIABLE>(sqrt). 

<ENDRETTEXT> 

This example may produce the following output. 


RETURNS The square roots of F_Floating, D_Floating, and G—Floating input parameters 

are returned by immediate value in RO and Rl. The square root of an H— 
Floating parameter is returned by reference in the output parameter sqrt. 
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<ROUTINE> 


<ROUTINE> 

Begins a new routine description. 

FORMAT 

<ROUTINE> (routine-name[ \ info 1[ \ info2]]) 

ARGUMENTS 

routine-name 

Specifies the name of the routine to be described. 

infol 

info2 

Specifies an optional text description of the routine's function. 

related tags 

• < ROUTINE-SECTION > 

• < SET-TEMPLATE-ROUTINE > 

required 

terminator 

None. 


DESCRIPTION Use the < ROUTINE > tag to begin a description section for a single routine 

in the context of the < ROUTINE-SECTION > tag. This tag has the following 
default format: 


• Each < ROUTINE > tag begins a new page of output. 

• Each output page carries a single running title, which is the current 
routine name. 

• If the optional info arguments are used with the < routine > tag, these 
arguments are output after the routine-name argument and are separated 
from the routine-name argument by an em dash (—). 

If you wish to replace the < routine > tag with a tag whose name is more 
meaningful to you (for example, <DCL-ROUTINE > ), or if you wish to change 
the default attributes of the < ROUTINE > tag, you should use the < set- 
template-routine > tag. See the description of the <SET-TEMPLATE- 
ROUTlNE> tag in this chapter for more information. 
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<ROUTINE> 


In the following example, the < ROUTINE-SECTION > tag enables the tags for a 
routine description. 


The description of the routine $OPEN will have the following default 
attributes: 

• The routine description will start a new page. 

• If the routine carries for more than a page, the name "$OPEN" will be 
carried as a running top title on each page. 

g <ROUTINE>($CLOSE\Close a File) 

When two arguments are specified to the < ROUTINE > tag, the routine 
name, $CLOSE, appears at the beginning of the routine description. The text 
specified in the second argument, "Close a File," follows the routine name at 
the top of the page, separated from the routine name by an em dash (—). 

2 <ROUTINE>(SMG$BEGIN_PASTEBOARD_UPDATE\\Begin Batching of Pasteboard Updates) 

This example illustrates special coding required when a routine's name is 
extremely long and may require special formatting. If the second argument is 
null, the third argument is stacked under the first argument. No em dash is 
output: 

SMG$BEGIN_PASTEBOARD_UPDATE 
Begin Batching of Pasteboard Updates 

Use this form only if the output from the other formats appears wrong. 

2 <ROUTINE>(OTS$SCOPY_R_DX\Copy a Source String \Passed by Reference to a 
Destination String) 

This example illustrates special coding required when a routine's name and 
descriptive name creates unreasonable output using the default formatting 
attributes. If you specify three arguments, the first and second arguments 
are output on the first line, separated by an em dash. The third argument is 
stacked under the first argument (instead of wrapping) following the em dash: 

0TS$SC0PY_R_DX—Copy a Source String 
Passed by Reference to a Destination String 

You will want to use this form only if examination of your output indicates a 
formatting problem. 


EXAMPLES 


<ROUTINE_SECTION> 

<R0UTINE>($0PEN) 

<0VERVIEW> 
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<ROUTINE_SECTION> 



ARGUMENTS running-title 

Specifies a top-level running heading to be used throughout the routine 
section. If this argument is not specified, the running headings are determined 
as described in Section 8.4.2. 

number-prefix 

Specifies a character-string prefix to be used to construct page numbers 
(folios) and formal figure, table, and example numbers. If this argument is 
not specified, the page and formal element numbering are determined as 
described in Section 8.4.2. 

NEWPAGE 

Indicates that the routine section should begin on a new page. This argument 
is only meaningful in two cases; 

• When you have previously entered the < SET_TEMPL ATE-ROUTINE > tag 
with the NONEWPAGE keyword to specify that each new routine in this 
routine section should not begin on a new page 

• When you want to place one or more pages of text between the end of a 
part page and the beginning of a routine section. 

related tags • <set_template_routine> 

• <SET_TEMPLATE_PARA> 

• <SET_TEMPLATE_LIST> 

• < SET-TEMPLATE-TABLE > 

• <SET_TEMPLATE-HEADING> 

• < ROUTINE > 

• < OVERVIEW > 

• <FORMAT> 

• <FRTN> 

• <FARGS> 

• <FARG> 

• <FFUNC> 
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restrictions 

required 

terminator 

DESCRIPTION 
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<ROUTINE_SECTION> 


• <RETURNS> 

• <RETTEXT> 

• <ARGDEFLIST> 

• <ARGITEM> 

• <ARGDEF> 

• <ARGTEXT> 

• < DESCRIPTION > 

• <RSDEFLIST> 

• <RSITEM> 

• <EXAMPLE_SEQUENCE> 


None. 


< ENDROUTINE -SECTION > 


The <ROUTlNE_SECTlON> tag begins a routine reference section. You can 
place more than one routine section within a single document, however, each 
previous routine section must be ended before the next one is begun. 

You can tailor the default format of the routine reference template to meet 
your own documentation requirements. You can either alter the default 
attributes of the <ROUTlNE_SECTlON> tag by specifying one of the arguments 
to that tag, or you can use the <SET_TEMPLATE-ROUTINE > tag to alter the 
default attributes for the < routine > tag that begins each new routine 
description. 

You can place a routine section within a chapter or an appendix, or following 
a part page (that is, within a document section begun with the < PART-PAGE > 
tag). You code a routine section in a chapter or an appendix in the same 
manner; command sections in parts are handled differently. 

If your routine section follows a part page, and you include text between 
the part page and the routine section, specify the NEWPAGE keyword as 
the third argument to the < ROUTINE-SECTION > tag. This causes the routine 
section to begin on a new page. The following code fragment shows a routine 
section that begins on a new page: 

<ROUTINE_SECTION>(\AB\NEWPAGE) 

<HEAD1>(Routine Format) 

When you use the < ROUTINE-SECTION > tag within a chapter or an appendix, 
and you want to place text after the routine section in that chapter or 
appendix, you must end the routine section with the < ENDROUTINE- 
SECTION > tag and place the text after that tag. By default, this text begins on 
a new page of output. 
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<ROUTINE_SECTION> 


Specify the NONEWPAGE argument to the <endroutine_section> tag if 
you do not want the text to begin on a new page of output. The following 
code fragment shows the end of a routine section that specifies that the 
subsequent text not placed on a new page: 

<ENDROUTINE^SECTION>(NONEWPAGE) 

When the <endroutine-SECTION > tag is specified within the context of a 
chapter or appendix, it resets the default running titles to those in effect for 
the chapter or appendix, so the last page of the last routine description in the 
routine section may not carry the last routine's name as the running heading. 
Instead it may carry the running title used by the chapter or appendix. 


EXAMPLES The following example shows how to begin a routine section within a 

document part. 

n <PART> 

<PART_PAGE> 

<TITLE>(PART II\AAA Routine Descriptions) 

<ABSTRACT>This Part contains complete reference descriptions of 
the AAA routines. 

<ENDABSTRACT> 

<ENDPART_PAGE>(RENUMBER) 

<ROUTINE_SECTION>(AAA Routines\AAA) 

<SET_TEMPLATE_ROUTINE>(AAA_ROUTINE\DOUBLERUNNINGHEADS) 

<AAA_ROUTINE>(AAA$CL0SE) 

<0VERVIEW> 

Closes the specified file. 

<ENDOVERVIEW 


<ENDROUTINE_SECTION> 

The tags in the previous example perform the following functions: 

• The global <part> tag begins the part. 

• The global <part_page> tag creates a part page. 

• The global < TITLE > tag is used in the context of the <part_page> tag 
to create a title on the part page. 

• The RENUMBER argument to the global <ENDPART_PAGE> tag specifies 
that the pages should be renumbered beginning with the part page. This 
causes the first page of text following the part page to be numbered page 
3 (Page 1 is the unnumbered page the part page title is placed on, page 2 
is the back of page 1, and page 3 is the first numbered page after the part 
page). 

• The < ROUTINE-SECTION > tag begins the routine section and specifies the 
running title "AAA Routines" as the running title for the routine section. 

The <ROUTiNE-SECTlON> tag also specifies that the prefix "AAA" should 
be used to construct numbers for pages and for formal figures, tables, 
and examples within the routine section (for example, AAA-11, AAA-32, 
Table AAA-1, Example AAA-2, and so on). 
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• The <SET_TEMPLATE-ROUTINE > tag specifies that all routine descriptions 
in this routine section will be identified using the tag <AAA_ROUTiNE> 
rather than the default <ROUTiNE> tag. The <aaa_routine> tag will 
have the default attributes of the < ROUTINE > tag. 

The DOUBLERUNNINGHEADS argument to the <SET-TEMPLATe_ 
ROUTINE > tag specifies that the routine section should have a double 
running heading at the top of the page. The top heading is the runnings 
title specified as an argument to the < routine-SECTION > tag, and the 
lower heading is the name of the current routine. 

The following example shows how you can create a routine section in which 
each routine description (begun with a < ROUTINE > tag) is in a separate 
SDML file, and all these descriptions are included into a primary routine 
description file. For example, the file MYROUTINES.SDML contains the 
following SDML tags: 

<INCLUDE>(AAA$CL0SE.SDML) 

<INCLUDE>(AAA$0PEN.SDML) 

<INCLUDE>(AAA$READ.SDML) 

<INCLUDE>(AAA$WRITE.SDML) 

Each of the included files contains one routine reference description begun 
with a < ROUTINE > tag. For these files to process correctly, they must be 
preceded with the < ROUTINE-SECTION > tag that enables the < ROUTINE > 
tag. These files can have the necessary tags processed before them by 
specifying the /INCLUDE qualifier on the command line to include a startup 
definition file. This startup file might include the following tags. 

g <ROUTINE_SECTION>(AAA RoutinesNAAA) 

<SET_TEMPLATE_ROUTINE>(ROUTINE\DOUBLERUNNINGHEADS) 

If this startup file were named AAAROUTINE—STARTUP.SDML, it could 
be included using the DOCUMENT /INCLUDE qualifier as in the following 
example: 

$ DOCUMENT myroutines SOFT.REF LN03 /INCLUDE=AAAROUTINE_STARTUP.SDML 

When each individual file in MYROUTINES.SDML is processed, the correct 
sequence of tags will be read in to begin the routine section. 

You can process multiple files together by using the <INCLUDE> tag to 
include them into a single master file (such as MYROUTINES.SDML), or you 
can include them into a book build profile. 

You use the <ELEMENT> tags to include multiple files into a profile. For 
example, the book build profile file AAAPRO.SDML could contain the 
following tags: 

<PR0FILE> 

<ELEMENT>(AAA$CLOSE.SDML) 

<ELEMENT>(AAA$0PEN.SDML) 

<ELEMENT>(AAA$READ.SDML) 

<ELEMENT>(AAA$WRITE.SDML) <C0MMENT>(contains <ENDROUTINE_SECTION> tag) 
<ENDPROFILE> 

Note that the profile file should include the <endroutine-Section > tag 
in the appropriate file, so that the template will be terminated and the book 
build will process correctly. 
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<RSDEFLIST> 


<RSDEFLIST> 


Begins a return status definition list in the routine template. 

FORMAT 

NONE ] 

<RSDEFLIST> [( < alternate-heading[ \ NONE] > )] 

, [alternate-heading] \ TEXT J 

ARGUMENTS 

alternate-heading 

Specifies a heading to override the current default text heading for this use of 
the <RSDEFLIST> tag. The default heading provided by VAX DOCUMENT 
is "Return Values." See the reference description of the <SET_TEMPLATE_ 
HEADING > tag for information on how to modify the default headings for all 
<RSDEFLIST> tags. 


TEXT 

Specifies that a block of text should appear in place of a list of return status 
values. If you use this keyword, it must be positioned as the second argument 
to the <RSDEFLIST> tag. 


To use the default heading and to indicate that text follows, specify the 
following: 


<RSDEFLIST>(\TEXT) 


NONE 

Indicates that the routine does not return any values. 

related tags 

• <RSDEFLIST> 


• <RSITEM> 

restrictions 

If NONE is specified as an argument to the <rsdeflist> tag, the 
<ENDRSDEFLIST> tag should not be used. 

required 

terminator 

<ENDRSDEFLIST> 

DESCRIPTION 

The <RSDEFLIST> tag begins a two-column table listing the return 
status of the routines listed. VAX DOCUMENT formats this table as a 
multipage table, which means that the <TABLE_ROW_BREAK> (FIRST) and 
<TABLE_ROW_BREAK> (LAST) tags can be used to control page breaks within 
the table if such control is needed. 
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<RSDEFLIST> 


EXAMPLES The following example illustrates a return status definition list for a routine 

with two possible return values. 

g <RSDEFLIST> 

<RSITEM>(SS$_NORMAL\Service successfully completed.) 

<RSITEM>(SS$_ACCVIO\Access violation.) 

<ENDRSDEFLIST> 


This example may produce the following output. 


RETURN 

VALUES 


SS$_NORMAL 

SS$_ACCVIO 


Service successfully completed. 
Access violation. 


The following example uses the NONE keyword argument to indicate that a 
routine does not return any status values. Note that <ENDRSDEFLIST> must 
not be specified. 

2 <RSDEFLIST>(NONE) 

This example may produce the following output. 


RETURN None. 

VALUES 

The following example illustrates a single line of descriptive text in a Return 
Status section. 

g <RSDEFLIST>(\TEXT) 

Any condition values returned by the Record Management Service (RMS), 

Parse. 

<ENDRSDEFLIST> 


This example may produce the following output. 


RETURN 

VALUES 


Any condition values returned by the Record Management Service (RMS), 
Parse. 
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<RSITEM> 


<RSITEM> 

Specifies the return status value of a routine and lists its meaning. 

FORMAT 

<RSITEM> (code \ code-description) 

ARGUMENTS 

code 

Specifies the system keyword assigned to the status value. 

code-description 

Specifies the descriptive text explaining the meaning of the return status 
value. 

related tags 

• <RSDEFLIST> 

restrictions 

Valid only within the context of the <RSDEFLIST> tag. 

required 

terminator 

None. 

EXAMPLES 

These examples show only code fragments and no actual output. See the 
<RSDEFLIST> tag description for sample output. 


<RSDEFLIST> 

<RSITEM>(SS$_NORMAL\Normal, successful completion.) 
<RSITEM>(SS$_ACCVIO\Access violation.) 
<ENDRSDEFLIST> 


This example illustrates a Return Status section for a routine that has two 
possible return values. 

<RSDEFLIST> 

<RSITEM>(SS$_NORMAL\Normal successful completion.) 

<RSITEM>(SMG$_WRONNUMARG\Wrong number of arguments.) 

<RSITEM>(<SPAN>(2\LEFT)Any condition values returned by 
LIB$SCOPY_DXDX. SMG$ADD_KEY_DEF. or by CLI$ routines.) 

<ENDRSDEFLIST> 


This example illustrates the Return Status definition list for a routine that 
has two specific return values and uses the <SPAN> tag to place additional 
explanatory text within the table. 
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<SET_TEMPLATE_ROUTINE> 


<SET_TEMPLATE^ROUTINE> 


Defines a new reference element tag name to use in the routine template, 
and specifies the formatting attributes for the new tag. 


FORMAT <SET_TEMPLATE_ROUTINE> (tag-name 

[ \ attribute] 
[ \ attribute] 
[ \ attribute]) 


ARGUMENTS tag-name 

Specifies the name of the template tag being defined. This tag name must 
be a valid tag name less than 31 characters; it must not be the same as an 
existing SDML tag name other than "ROUTINE" (which is the default tag 
name). 

attribute 

Specifies one of the following three keywords to override the default 
attributes for the < ROUTINE > tag. 

• NONEWPAGE 

Routine descriptions are not to start on new pages. By default, each 
tag-name template tag begins a routine description on a new page. 

• DOUBLERUNNINGHEADS 

Specifies that the routine descriptions will have two running titles at 
the top of every page. The top running title is either the title you set 
with the < ROUTINE-SECTION > tag, or the heading set in the most recent 
<CHAPTER> or <APPENDIX> tag. By default, if a doctype does not call 
for running top titles, only the current routine name is placed at the top 
of each page. 

• STACK 

Specifies that when multiple arguments are specified for the tag-name tag, 
the arguments should be stacked at the beginning of the page. 

By default, when multiple arguments are specified, the second and third 
arguments are assumed to be optional descriptive information, and are 
output as shown in the examples in the <routine> tag description. 


related tags • <routine_section> 

• < routine > 


restrictions Valid only within the context of the <ROUTlNE_SECTlON> tag. 
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<SET_TEMPLATE_ROUTINE> 


required None. 

terminator 


DESCRIPTION The <SET_TEMPLATE_ROUTiNE> tag lets you change the name of the 

< ROUTINE > tag, making the coding of your source files more meaningful. 

This tag also lets you change the default attributes associated with the 

< ROUTINE > tag or your new tag. 


EXAMPLES 

g <ROUTINE_SECTION>(FDL RoutinesWNEWPAGE) 

<SET_TEMPLATE_ROUTINE>(FDL_ROUTINE\NONEWPAGE\STACK\DOUBLERUNNINGHEADS) 

<FDL_ROUTINE>($STARTUP_FILE\$STF) 

This tag sequence begins a routine section and defines the tag <FDL_ 

ROUTlNE> as the routine descriptor tag. The attributes set are as follows: 

• Routines do not start on new pages. However, because NEWPAGE is 
specified to <ROUTiNE_SECTlON> , the first reference description will 
begin on a new page. 

• When two arguments are specified to the tag <FDL-ROUTINE > , the 
arguments are stacked; that is, the second argument is placed under the 
first on output. 

• Each page carries a two-line running title. The top line is "FDL Routines" 
and the second line is the name of the routine description that is current 
at the top of the page. 

Note that this routine sequence is most appropriate for a series of routine 

descriptions that occur within a chapter. 


H <PART> 

<PART_PAGE> 

<TITLE>(PART II\XYZ Routines) 

<ENDPART_PAGE>(RENUMBER) 

<ROUTINE_SECTION>(XYZ Routines\XYZ) 

<SET_TEMPLATE_ROUTINE>(XYZ_ROUTINE) 

This tag sequence begins a document part in which only routine descriptions 
occur. The RENUMBER argument on the <endpart_page> tag specifies 
that the first page of the new Part (the part page itself) should be numbered 
page 1. The <routine_section> tag sets the folio prefix to XYZ; that is, 
pages will be numbered XYZ-3, XYZ-4, and so on. 

No attributes are specified for the routine descriptions produced by <XYZ_ 
ROUTINE > . These routines will have default attributes. The first routine will 
start on a new page. Because RENUMBER was specified on <ENDPART_ 
PAGE> , the first routine will be on the page numbered XYZ-3. 
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14.5 The Statement Reference Template Tags 

This section alphabetically describes the tags available in the Statement 
template. Use these tags to create a statement reference section. In most 
manuals, a statement section is an encyclopedic reference section that 
describes each statement the software system offers, the statement's format, 
its arguments, and examples of its use. 


14-151 


SOFTWARE Doctype Tag Reference 

<CONSTRUCT> 


<CONSTRUCT> 


Specifies a variable construct and gives its expansion. 

FORMAT 

<CONSTRUCT> [(construct-name)] 

ARGUMENTS 

construct-name 

Specifies the name of a construct. If this argument is omitted, text following 
the <CONSTRUCT> tag is formatted as if text had been specified; that is, the 
text is set at the same margin as additional construct items. 

related tags 

• <CONSTRUCT_LIST> 

• <STATEMENT_LINE> 

restrictions 

Valid only within the context of the <STATEMENT_FORMAT> tag. 

required 

terminator 

None. 

EXAMPLE 

The following example shows statement format for a statement with a single 
construct list. Note the use of <LIST> tags to specify the output and the 
< KEYWORD > tag to control the representation of programming keywords 
within variable name text. 

<statement_format> 

<FCMD>(REMAP) <FPARMS>((map-nam) remap-itein,<hellipsis>) 

<construct_list>(remap-item:) 

<construct>(remap-item:)<list>(stacked\braces) 

<le>iium-vbl-nam 

<LE>str-array-nam ( [ int-exp,<hellipsis>] )[ = int-exp ] 

<LE>[ data-type ] <keyword>(FILL) [ ( int-exp) ] [ = int-exp ] 

<LE><keyword>(FILLy,) [ ( int-exp ) ] 

<LE><keyword>(FILL$) [ ( int-exp ) ] [ = int-exp ] 

<endlist> 

<endconstruct_list> 

<endstatement_format> 


This example may produce the following output. 


Format 


REMAP (map-nam) remap-item, . . . 
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<CONSTRUCT> 


remap-item: 


' num-vbl-nam 

str-array-nam ([int-exp, ...])[= int-exp ] 

< [data-type]F\LL[(int-exp)][= int-exp] ^ 

F[IL% [(int-exp}] 

FILLS [ (int-exp) ][= int-exp ] 
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<CONSTRUCT_ 

LIST> 

<CONSTRUCT_LIST> 

Begins a list of construct items and definitions that expand on variables 
specified in the context of the <statei\/ient_format> tag. 

FORMAT 

<CONSTRUCT_LIST> (construct-name) 

ARGUMENTS 

construct’name 

Specifies the text of the longest name that will be referenced in the construct 
list; that is, a name specified as an argument to <CONSTRUCT> . 

related tags 

• < CONSTRUCT > 

• <STATEMENT_LINE> 

restrictions 

Valid only within the context of a < STATEMENT-FORMAT > tag section. 

required 

terminator 

< ENDCONSTRUCT-LIST > 

DESCRIPTION 

A construct list is a set of semantic rules for a programming language. Each 
item in a construct list is a semantic entity that may expand to one or more 
sets of additional constructs or entities. Using the global <LIST> tag in a 
construct list within a statement section, you can present the semantic rules 
for language statements in a highly-structured way. 

EXAMPLES 

The following example shows a construct list with only one construct. 


<statement_format> 

<fcmd>(<list>(stacked\braces) 

<le>C0M 

<le>COMMON<endlist>) <fparms>([ ( com-nam ) ] {[data-type ] com-item },<hellipsis>) 
<construct_list>(com-item:) 

<construct>(com-item:) 

<list>(stackedXbraces) 

<le><VARIABLE>(num-unsubs-vbl-nam) 

<le><VARIABLE>(num-array-nam ( int-const,<hellipsis>)) 
<le><VARIABLE>(str-unsubs-vbl-nam = int-const) 

<le><VARIABLE>(str-array-nam ( int-const,<hellipsis> ) [ = int-const ]) 
<le><VARIABLE>(<keyword>(FILL) [ ( int-const ) ][ = int-const ]) 
<le><VARIABLE>(<keyword>(FILL7,) [ ( int-const ) ]) 

<le><VARIABLE>(<keyword>(FILL$) [ ( int-const ) ][ = int-const ]) 

<endlist> 

<endconstruct_list> 

< endstat ement _f ormat > 
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<CONSTRUCT_LIST> 


This example may produce the following output. 


Format 


r COM 
I COMMON 


[ ( com-nam ) ] {[data-type ] corn-item . 


corn-item: 


num-unsubs-vbl-nam 
num-array-nam (int-const, . . . ) 
str-unsubs-vbl-nam = int-const 
< str-array-nam (int-const ...)[= int-const ] > 
FILL /■ (int-const) ][= int-const ] 

FILL% [ ( int-const) ] 

FILLS [ (int-const ) ][= int-const ] J 


The following example illustrates a construct list with more than one 
construct. The argument to <CONSTRUCT_LlST> is used to set the margins 
for the individual items identified by <CONSTRUCT> tags. Note that the text 
of the longest item, formal-param: is specified. 


<FCMD>(<list>(stacke<i\braces) 

<le>END SUB 

<le>SUBEND<endlist>) <FPARMS>() 

<construct_list>(formal-param:) 

<construct>(pass-mech:)<list>(stackedXbraces) 

<le><keyword>(BY DESC) 

<le><keyword>(BY REF)<endlist> 

<construct>(formal-param:) 

[ data-type ] <list>(stackedXbraces) 

<le>unsubs-vbl-nam 

<le>array-nam ( <list>(stackedXbrackets) 

<le>int-const 
<le><keyword>(.)<endlist> 

<list>(stacked) 

<le><keyword>(,<hellipsis>) 

<le><keyword>(<hellipsis>)<endlist>)<endlist> 

<endconstruct_list> 

<endstatement_format> 


This example may produce the following output. 
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<CONSTRUCT_LIST> 


Format 

f END SUB 1 
I SUBEND J 


pass-mech: 


{ BY DESC 1 
I BY REF / 


formal-param: [ data-type ] 
( unsubs-vbl-nam 

array-nam (' 
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<FCMD> 

Specifies a statement or function keyword and an optional parameter list 
within the context of the <statement_format> tag. 

FORMAT 

< FCMD> (statement-keywordf \ parameter-list]) 

ARGUMENTS 

statement-keyword 

Specifies the name of the first part of the format statement; typically this is 
the principal statement name or the function name. This text is output in the 
left portion of the format description. 

parameter-list 

Specifies one or more parameters of the statement or function ke)rword. 

This text is output to the right of the statement or function in the format 
description with no space between the statement-keyword and the parameter- 
list text. 

Parameters you specify using the parameter-list argument are output 
differently than parameters specified using the <fparms> tag. See the 
examples in this tag description for illustrations of these differences. 

related tags 

• <FFUNC> 

• <FPARM> 

• <FPARMS> 

• <STATEMENT_FORMAT> 

• <STATEMENT_SECTION> 

restrictions 

• Valid only within the context of the < format > or 
<STATEMENT_FORMAT> tags. 

• If you do not provide a second argument to the <fcmd> tag, you should 
explicitly declare the absence of parameters by using the <FPARMS> tag 
as follows: 

<FCMD>(STATEMENT-KEYWORD) <FPARMS>() 

If you do not specify a second argument to the <fcmd> tag and the 
<FPARMS> tag is not specified, VAX DOCUMENT issues a warning 
message. 

required 

None. 


terminator 
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<FCMD> 



Format 

EXIT 


The following example specifies both the statement-keyword and the 
parameter-list arguments to the <fcmd> tag. Note in the output sample 
how these two arguments are formatted together with no intervening spaces. 
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<FCMD> 


<STATEMENT_FQRMAT> 

<FCMD>(RETURN\ident_field, numeric_field) 
<ENDSTATEMENT_FORMAT> 


This example may produce the following output. 


Format 

RETURf^ident—field, numeric—field 


The following example specifies a statement keyword with a single parameter 
using the <FCMD> and <FPARMS> tags. Note that coding the parameters 
using the <fparms> tag results in a space being output between the 
command keyword and the parameter. 


<STATEMENT_FORMAT> 

<FCMD>(RECORD) <FPARMS>(rec-nam) 
<ENDSTATEMENT_FORMAT> 


This example may produce the following output. 


Format 

RECORD rec-nam 

The following example specifies the <FCMD> tag using the global 
<KEYWORD> tag as part of the parameter-list argument text. Note how 
the global <KEYW0RD> tag alters the output. The output of this example is 
shown in Output Sample 5. 

□ <STATEMENT_FORMAT> 

<FCMD>(RETURN\ident.field, numeric.field,<keyword>([/LENGTH] )) 

<ENDSTATEMENT_FORMAT> 


This example may produce the following output. 


Format 

RETURN ident—field, numeric—field,[/LEl^GTH] 
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<FFUNC> 


<FFUNC> 

Labels a function within the context of a <statement_format> tag 
section. 

FORMAT 

<FFUNC> ([return-val\]function-name 
\ argument-list) 

ARGUMENTS 

return-val 

Specifies a variable name to which a function returns its value. 

function-name 

Is the name of the function. 

argument-list 

Specifies the function's argument list. 

related tags 

• <STATEMENT_FORMAT> 

restrictions 

Valid only within the context of the <STATEMENT_format> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <FFUNC> tag is used with the context of the <STATEMent_format> tag 
to output the syntax of a function. This tag allows the user to create a syntax 
which includes the following: 


• The name of the function 


• The return value of the function 

• Any arguments that the function may require 
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<FORMAT_SUBHEAD> 


< FORMAT. 

_SUBHEAD> 

Introduces one of a set of multiple formats in a statement format section. 

FORMAT 

<FORMAT_SUBHEAD> (heading-text) 

ARGUMENTS 

heading-text 

Specifies the text of the heading to be used before a specific format 
presentation. 

related tags 

• <FCMD> 

• <FPARMS> 

• <STATEMENT_FORMAT> 

restrictions 

Valid only within the context of the <STATEMENT_FORMAT> tag if 
the MULTIPLE keyword was specified as the second argument to the 
<STATEMENT_FORMAT> tag. 

required 

terminator 

None. 

EXAMPLE 

The following example shows how to use the < FORMAT-SUBHEAD > tag in a 
series of formats for a single statement. 


<statement_format>(\multiple) 

<FORMAT_SUBHEAD>(String Variable To Array) 

<FCMD>(CHANGE) <FPARMS>(str-exp <KEYW0RD>(T0) num-array) 
<FORMAT_SUBHEAD>(Array to String Variable) 

<FCMD>(CHANGE) <FPARMS>(num-array <KEYW0RD>(TO) str-vbl) 
<endstatement_format> 


This example may produce the following output. 
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Format 

String Variable To Array 

CHANGE str-exp TO num-array 

Array to String Variable 

CHANGE num-array TO str-vbl 
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<FPARM> 

Adds a single parameter line to a list of parameters in a statement syntax 
format section. 

FORMAT 

<FPARM> (parameter-name) 

ARGUMENTS 

parameter-name 

Specifies a single-line item to be formatted in a format parameter list. 

related tags 

• <STATEMENT_SECTION> 

• < STATEMENT-FORMAT > 

• <FCMD> 

• <FPARMS> 

restrictions 

Can only be specified following an <FCMD> tag and <fparms> tag 
sequence in a format section. 

required 

terminator 

None. 

EXAMPLE 

The following example shows a sample use of the <fparm> tag. 


<F0RMAT> 

<fcmd>(SET TERMINAL) <fparm8>([device-name[:]]) 

<f parin> (/DEVICE_TYPE=< 1 i st > ( st acked\br ac e s) 

<le><keyword>(UNKNOWN) 

<le><keyword>(LA34) 

<le><keyword>(VTIOO) 

<le><keyword>(PRO_SERIES)<endlist>) 
<f parin> (<list> (stackedXbrackets) 

<le>LINE_EDITING 

<le>NOLINE_EDITING<endlist>) 

<f parin> (<list> (stackedNbrackets) 

<le>PASSALL 

<le>NOPASSALL<endlist>) 

<ENDFORMAT> 


This example may produce the following output 
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<FPARM> 


FORMAT SET TERMINAL [device-namef:]] 

/DEVICE-TYPE= 
UNKNOWN ) 
LA34 

VT100 I 
I PRO-SERIES > 

/LINE-EDITING 
/NOLINE-EDITING 
' /PASSALL 1 
/NOPASSALL 
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<FPARMS> 


<FPARMS> 

Specifies the parameters to a statement or function within the context of 
the <STATEMENT_FORMAT> tag. 

FORMAT 

<FPARMS> (parameter-list) 

ARGUMENTS 

parameter-list 

Specifies one or more parameters to a statement or function. 

You can also use this argument to explicitly declare that a statement or 
function marked with the <FCMD> tag has no parameters, as shown in the 
following example. 

<FCMD>(EXIT) <FPARMS>() 

Parameters you specify using the <FPARMS> tag are printed differently than 
parameters specified in the parameter-list argument to the <FCMD> tag. See 
the examples in this tag description for illustrations of the different output 
styles. 

related tags 

• <FCMD> 

• <FFUNC> 

• <STATEMENT_FORMAT> 

• <STATEMENT_SECTION> 

restrictions 

The <FPARMS> tag should be used with the <FCMD> tag in the context of 
the <STATEMENT_FORMAT> tag. 

required 

terminator 

None. 

DESCRIPTION 

The <FPARMS> tag formats the parameter portion of a statement or function 
in the context of the <statement_format> tag. 

When you use this tag to define a parameter list that contains multiple words 
or text strings, include blank spaces between the words and text strings 
(including punctuation) according to the syntax rules of the function or 
statement you are describing. 

If the parameter-list argument text will not fit on one line, suitable line breaks 
are chosen based on the presence of spaces. Hyphenated text is not broken 
across lines. 

Use the <FPARM> tag to select explicit line breaks in a parameter list. 
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<FPARMS> 


EXAMPLES The following example uses the <FPARMS> tag to list an additional statement 

keyword within the parameters portion of a statement format. 

Q <FCMD>(END RECORD) <FPARMS>([ rec-nam ]) 

This example may produce the following output. 


Format 

END RECORD [ rec-nam ] 

The following example shows how to represent variable choices within the 
<FPARMS> parameter-list. 

H <statemeiit_format> 

<FCMD>(MAT READ) <FPARMS>(<list>(stacked\braces) 

<le> array <list>(stacked\brackets)<le> ( int-expl 
<list>(stacked\brackets)<le> , int-exp2 <endlist> ) <endlist> 

<endlist>,<hellipsis>) 

<endstatement_format> 

This example may produce the following output. 


Format 

MAT READ | array (int-exp 1 [, int-exp2 ] ) 
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<FUNCTION> 


<FUNCTION> 

Begins a new function description. 

FORMAT 

<FUNCTION> (function-name) 

ARGUMENTS 

function-name 

Specifies the name of the function to be described. 

related tags 

• < STATEMENT > 

• < SET_TEMPL ATE-STATEMENT > 

required 

terminator 

None. 

DESCRIPTION 

Use the <FUNCTlON> tag to begin a description section for a single function 
in the context of the < STATEMENT-SECTION > tag. This tag has the following 
default format: 

• Each <FUNCTiON> tag begins a new page of output. 

• Each output page carries a single running title, which is the current 
function name. 


Use the < SET-TEMPLATE-STATEMENT > tag to replace the <FUNCTION> tag 
with a tag whose name is more meaningful to you (for example, <ABC- 
FUNCTiON> ), or to change the default attributes of the < FUNCTION > tag. See 
the description of the <SET-TEMPLATE-STATEMENT> tag in this chapter for 
more information. 

Note that the <FUNCTiON> and the <STATEMENT> tags work in exactly the 
same manner. The two tag names are provided so that you may encode your 
source file more genetically. 

EXAMPLE 

In the following example, the < STATEMENT-SECTION > tag enables the tags for 
a function description. The description of the function OPEN will, by default, 
have the following attributes: 


• The function description begins on a new page. 

• If the function carries for more than a page, the name "OPEN" is carried 
as a running top title on each page. 


<STATEMENT_SECTION> 

<FUNCTI0N>(0PEN) 

<0VERVIEW> 
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<SET_TEMPLATE_STATEMENT> 


<SET_TEMPLATE_STATEMENT> 


Defines a new reference element tag name to use in the statement 
template and specifies the formatting attributes for the new tag. 


FORMAT <SET_TEMPLATE_STATEMENT> (tag-name 

[ \ attribute] 
[\ attribute] 
[ \ attribute]) 


ARGUMENTS tag-name 

Specifies the name of the template tag being defined. This tag name must 
be a valid tag name less than 31 characters; it must not be the same as an 
existing SDML tag name other than "STATEMENT" or "FUNCTION" (which 
are the default tag names). 

attribute 

Specifies one of three keywords that override the default attributes for the 
<STATEMENT> tag. 

• NONEWPAGE 

Specifies that statement descriptions are not to start on new pages. By 
default, each tag-name template tag begins a statement description on a 
new page. 

• DOUBLERUNNINGHEADS 

Specifies that the statement descriptions will have two rupnirig titles at 
the top of every page. The top running title is set by the <STATEMENT_ 
SECTiON> tag or by the heading of the most recent <CHAPTER> or 
<APPENDIX> tag. By default, if a doctype does not call for running top 
titles, only the current statement name is placed at the tpp of each page. 

• STACK 

Specifies that when multiple arguments are specified for the tag-name tag, 
the arguments should be stacked at the beginning of the page. 

By default, when multiple arguments are specified, the second and third 
arguments are assumed to be optional descriptive information, and are 
output on the same line as the statement name. 


related tags • <statement> 

• <FUNCTION> 

• < STATEMENT-SECTION > 


restrictions Valid only within the context of the < STATEMENT-SECTION > tag. 
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<SET_TEMPLATE_STATEMENT> 


required None. 

terminator 


DESCRIPTION The <SET_TEMPLATE_STATEMENT> tag lets you change the name of the 

< STATEMENT > tag to a name that is more meaningful in your source files. 

This tag also lets you change the default attributes associated with the 
<STATEMENT> tag or your new tag. 


EXAMPLES 

Q <STATEMENT_SECTION> (BASIC StatementsWNEWPAGE) 

<SET_TEMPLATE_STATEMENT>(BASIC_STATEMENT\NONEWPAGE\DOUBLERUNNINGHEADS) 

<BASIC_STATEMENT>(STARTUP_FILE\STF) 

This tag sequence begins a statement section and defines the tag < BASIC- 
STATEMENT> as the Statement descriptor tag. The attributes set are as follows: 

• Statements do not start on new pages. 

• Each page carries a two-line running title. The top line is "BASIC 
Statements" and the second line is the name of the statement description 
that is current at the top of the page. 

Note that this statement sequence is most appropriate for a series of statement 
descriptions that occur within a chapter. 

ra <PART> 

<PART_PAGE> 

<TITLE>(PART II\XYZ Statements) 

<ENDPART_PAGE>(RENUMBER) 

<STATEMENT_SECTION>(XYZ StatementsNXYZ) 

<SET_TEMPLATE_STATEMENT>(XYZ_STATEMENT) 

This tag sequence begins a document part in which only statement 
descriptions occur. The RENUMBER argument on the <ENDPART_PAGE> 
tag specifies that the first page of the new part (the part page itself) should 
be numbered page 1. The < STATEMENT-SECTION > tag sets the folio prefix to 
XYZ; that is, pages will be numbered XYZ-3, XYZ-4, and so on. 

No attributes are specified for the statement descriptions produced by <XYZ- 
STATEMENT> ; these statements have default attributes. The first statement 
will start on a new page. Because RENUMBER was specified on <ENDPART_ 
PAGE> , the first statement will be on the page numbered XYZ-3. 
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<STATEMENT> 

<STATEMENT> 

Begins a new statement description. 

FORMAT 

<STATEMENT> (statement-name) 

ARGUMENTS 

statement-name 

Specifies the name of the statement to be described. 

related tags 

• <FUNCTION> 

• <SET_TEMPLATE_STATEMENT> 

• <STATEMENT_SECTION> 

required 

terminator 

None. 

DESCRIPTION 

Use the <STATEMENT> tag to begin a description section for a single 
statement in the context of the < STATEMENT-SECTION > tag. This tag has 
the following default format: 

• Each <STATEMENT> tag begins a new page of output. 

• Each output page carries a single running title, which is the current 
statement name. 

Use the <SET_TEMPLATE-STATEMENT > tag to replace the <STATEMENT> 
tag with a tag whose name is more meaningful to you (for example, 
<ABC-STATEMENT> ), or if you wish to change the default attributes of the 
< STATEMENT > tag. See the description of the < SET-TEMPLATE-STATEMENT > 
tag in this chapter for more information. 

EXAMPLES 

In the following example, the < STATEMENT-SECTION > tag enables the tags for 
a statement description. By default, the description of the statement OPEN 
has the following attributes: 


• The statement description begins on a new page. 

• If the statement carries for more than a page, the name "OPEN" is carried 
as a running top title on each page. 


<STATEMENT_SECTION> 

<STATEMENT>(OPEN) 

<0VERVIEW> 
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<STATEMENT_FORMAT> 


<STATEMENT_FORMAT> 

Begins a section that illustrates the syntax of a statement or function, 
including keywords and parameters. 

FORMAT 

< STATEM ENT_FORMAT> [([alternate-heading] 

[\ MULTIPLE])] 

ARGUMENTS 

alternate-heading 

Specifies a heading to override the current default text heading for this 
use of the <statement_format> tag. The default heading provided by 

VAX DOCUMENT is "Format." See the reference description of the <SET- 
TEMPLATE-HEADING > tag for information on how to modify the default 
headings for all <statemenT-FORMAT> tags. 

MULTIPLE 

Indicates that the statement has more than one format, and that each format 
will be introduced using the < FORMAT-SUBHEAD > tag. This keyword is valid 
only as the second argument to the < STATEMENT-FORMAT > tag. 

related tags 

• <FCMD> 

• <FFUNC> 

• <FPARMS> 

• <CONSTRUCT-LIST> 

• < STATEMENT-LINE > 

• <FORMAT-SUBHEAD> 

required 

terminator 

<ENDSTATEMENT_FORMAT> 

DESCRIPTION 

The <STATEMENT_FORMAT> tag Creates sections of text that describe the 
format of a statement or function. Like the global <format> tag, the 
<STATEMENT-FORMAT> tag enables the <fcmd> and <fparms> tags to 
label specific portions of a statement format section. 

The following is a list of some of the most regularly used statement format 
section tag combinations; 

• <FCMD>(statement-keyword) <FPARMS>(parameter-list) 

This is the standard form in which the statement keyword and its 
parameter list are separated by a blank space. If the parameter list, 
on output, is more than a single line, additional lines are aligned at the 
beginning of the parameter list. 


<FCMD>(statement-keyword\parameter-list) 
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<STATEMENT_FORMAT> 


This form should be used for statement functions, in which a statement 
and its parameters are not separated by blank spaces. 

Following the formatted statement, the <CONSTRUCT_LlST> and 
< STATEMENT-LINE > tags can be used to expand on the meanings of variable 
names specified in the format. Such variable names can be coded using thie 
<VARIABLE> or <KEYWORD> tags. 


EXAMPLES The following example shows a statement format section that uses the 

<FFUNC> tag to present the format of a statement. 

g <STATEMENT_FORMAT> 

<FFUNC>(real-vbl\=ABS<VARIABLE>((real-exp))) 

<endstatement_format> 


This example may produce the following output. 


Format 

rea I - vbl=yA BS(real-exp) 

The following example illustrates the use of multiple formats for a single 
statement, with special headings for each. Note the special use of the 
< FORMAT-SUBHEAD > tag to introduce each specific format. 

2 <statement_format>(\multiple) 

<FORMAT_SUBHEAD>(String Variable To Array) 

<FCMD>(CHANGE) <FPARMS>(str-exp <KEYW0RD>(TO) num-array) 

<FORMAT_SUBHEAD>(Array to String Variable) 

<FCMD>(CHANGE) <FPARMS>(num-array <KEYWORD>(TO) str-vbl) 

<endstatement_format> 


This example may produce the following output. 


Format 

String Variable To Array 

CHANGE Str-exp TO num-array 

Array to String Variable 

CHANGE num-array TO str-vbl 
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<STATEMENT_LINE> 


<STATEMENT_UNE> 

Indicates the position of a valid statement line within the context of a 
statement format or a construct list. 

FORMAT 

<STATEMENT_LINE> [(text[\INDENT])] 

ARGUMENTS 

text 

Specifies the text for a valid statement line. If no text is specified, the default 
statement line output is as follows: 

[ statement ] . . . 

INDENT 

Indicates that the statement line is to be indented from the margin at which 
the current statement format or construct list is being set. 

related tags 

• <FCMD> 

• <FPARMS> 

• <CONSTRUCT> 

restrictions 

Valid only in the context of the Statement reference template. 

required 

terminator 

None. 

EXAMPLES 

The following example shows how to use <statement_line> within a 
formatted statement section. 


<STATEMENT_FORMAT> 

<FCMD>(RECORD) <FPARMS>(rec-nam) 
<STATEMENT_LINE>(rec-component) 
<ELLIPSIS> 

<FCMD>(END RECORD) <FPARMS>([ rec-nam ]) 
<ENDSTATEMENT_FORMAT> 
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<STATEMENT_LINE> 


This example may produce the following output. 

Format 

RECORD rec-nam 

rec-component 


END RECORD [ rec-nam ] 


The following example shows how to use the <STATEMENT_line> tag within 
a construct list. Note that the first use of the tag specifies INDENT as the 
second argument. 


<STATEMENT_FORMAT> 

<CONSTRUCT_LIST>(group-clause:) 

<construct>(group-clause:) 

<keyword>(GROUP) group-nam [ ( int-const,<hellipsis> ) ] 
<statement_line>(rec-component\indent) 

<ellipsis> 

<statement_line>(<keyword>(END GROUP) [ group-nam ]) 
<ENDCONSTRUCT_LIST> 

<ENDSTATEMENT_FORMAT> 


This example may produce the following output. 


Format 

group-clause: GROUP group-nam [ (int-const ■ ■ ■ ) ] 

rec-component 


END GROUP [ group-nam ] 
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<STATEMENT_UNE> 


The following example shows the default output for the <STATEMENT_LINE> 
tag when it is used in a statement format section. 


<statemeiit_format> 

<FCMD>(SUB) <FPARMS>(sub-name [ pass-mech ] [ ( [ formal-param ], 
<hellipsis> ) ]) 

<statement_line> 

<FCMD>(<list>(stackedXbraces) 

<le>END SUB 

<le>SUBEND<endlist>) <FPARMS>() 

<endstatement_format> 


This example may produce the following output. 


Format 

SUB sub-name [ pass-mech ] [ ([ formal-param I ■■■} ] 
[statement]... 


r END SUB 1 
I SUBEND / 
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<STATEMENT_SECTION> 


<STATEMENT_SECTION> 


Begins a statement reference section, enables tags reserved for use in 
statement sections, and sets paging attributes. 


FORMAT 


<STATEMEIMT_SECTION> [([running-title] 

[ \ [number-prefix] 
[\NEWPAGE]])] 


ARGUMENTS running-title 

Specifies a top-level running heading to be used throughout the statement 
section. If this argument is not specified, the running headings are determined 
as described in Section 8.4.2. 

number-prefix 

Specifies a character-string prefix to be used to construct page numbers 
(folios) and formal figure, table, and example numbers. If this argument is 
not specified, the page and formal element numbering are determined as 
described in Section 8.4.2. 

NEWPAGE 

Indicates that the statement section should begin on a new page. This 
argument is only meaningful in two cases: 

• When you have previously entered the <SET_TEMPLATE—STATEMENT > tag 
with the NONEWPAGE keyword to specify that each new statement in 
this statement section should not begin on a new page 

• When you want to place one or more pages of text between the end of a 
part page and the beginning of a statement section. 


related tags • <set_template_statement> 

• <SET_TEMPLATE_PARA> 

• < SET-TEMPLATE-LIST > 

• <SET-TEMPLATE_TABLE> 

• <SET-TEMPLATE-HEADING> 

• <STATEMENT> 

• <FUNCTION> 

• <OVERVIEW> 

• < STATEMENT-FORMAT > 

• <FORMAT_SUBHEAD> 

• <FCMD> 

• <FPARMS> 
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<STATEMENT_SECTION> 


restrictions 

required 

terminator 

DESCRIPTION 


• <FFUNC> 

• <CONSTRUCT_LIST> 

• <CONSTRUCT> 

• <STATEMENT_LINE> 


None. 


< ENDSTATEMENT-SECTION > 


The < STATEMENT-SECTION > tag begins the statement reference template. 

You can locate a statement section within a chapter or an appendix, or 
following a part page (that is, within a document section begun with the 
<PART_PAGE> tag). You code a statement section in a chapter or an appendix 
in the same manner; statement sections in parts are handled differently. 

If your statement section follows a part page, and you include text between 
the part page and the statement section, specify the NEWPAGE keyword 
as the third argument to the < STATEMENT-SECTION > tag. This causes the 
statement section to begin on a new page. The following code fragment 
shows a statement section that begins on a new page: 

<STATEMENT_SECTION>(\SD\NEWPAGE) 

<HEAD1>(Statement Format) 

When you use the <STATEMENT-SECTlON> tag within a chapter or an 
appendix, and you want to place text after the statement section in 
that chapter or appendix, you must end the statement section with the 
<ENDSTATEMENT-SECTiON> tag and place the text after that tag. By default, 
this text begins on a new page of output. 

Specify the NONEWPAGE argument to the <ENDSTATEMENT-SECTiON> tag 
if you do not want the text to begin on a new page of output. The following 
code fragment shows the end of a statement section that specifies that the 
subsequent text not be placed on a new page: 

<ENDSTATEMENT_SECTION>(NONEWPAGE) 

When the <ENDSTATEMENT-SECTiON> tag is specified within the context of 
a chapter or appendix, it resets the default running titles to those in effect 
for the chapter or appendix, so the last page of the last statement description 
in the statement section may not carry the last statement's name as the 
running heading. Instead it may carry the running title used by the chapter 
or appendix. 

The < STATEMENT-SECTION > tag can be used more than once in a document. 
By specifying arguments to that tag, and by using the < SET-TEMPLATE- 
STATEMENT > tag to specify additional attributes, you can tailor statement 
sections that meet the specific requirements of your documentation. 
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<STATEMENT_SECTION> 


EXAMPLES The following example shows how to begin a statement section within a 

document part. 

g <PART> 

<PART_PAGE> 

<TITLE>(Part III\BASIC Statements and Functions) 

<ENDPART_PAGE>(RENUMBER) 

<STATEMENT_SECTION>(Statements and Functions\SF) 

<SET_TEMPLATE_STATEMENT>(BASIC_STATEMENT) 

<BASIC_STATEMENT>(GROUP) 

<0VERVIEW> 

Creates a group within a database. 

<ENDOVERVIEW 


<ENDSTATEMENT_SECTION> 

The tags in the previous example perform the following functions: 

• The global <part> tag begins the part. 

• The global <part_page> tag creates a part page. 

• The global <title> tag is used in the context of the <part_page> tag 
to create a title on the part page. 

• The RENUMBER argument to the global <ENDPART_PAGE> tag specifies 
that the pages should be renumbered beginning with the part page. This 
causes the first page of text following the part page to be numbered page 
3 (Page 1 is the unnumbered page the part page title is placed on, page 2 
is the back of page 1, and page 3 is the first numbered page after the part 
page). 

• The <STATEMENT_SECTiON> tag begins the statement section and 
specifies the running title "Statements and Functions" as the running 
title for the statement section. If the <SET_TEMPLATE—STATEMENT > tag 
were used with the DOUBLERUNNINGHEADS argument, the title 
"Statements and Functions" would be used as the top running title. 

The <STATEMENT_SECTiON> tag also specifies that the prefix "SF" should 
be used to construct numbers for pages and for formal figures, tables, and 
examples within the statement section (for example, SF-11, SF-32, Table 
SF-1, Example SF-2, and so on). 

• The <SET_TEMPLATE_STATEMENT> tag specifies that all statement 
descriptions in this statement section will be identified using the tag 
<BASIC_STATEMENT> rather than the default tags <function> or 
<STATEMENT> . The < BASIC-STATEMENT > tag created by the <SET_ 
TEMPLATE-STATEMENT> tag will have the default attributes of the default 
tags (the <FUNCTiON> and <statement> tags). 

The following example shows how you can create a statement section 

in which each statement description (begun with a < STATEMENT > or 
< FUNCTION > tag) is in a separate SDML file, and all these descriptions 

are included into a primary statement description file. For example, the file 

MYSTATEMENTS.SDML contains the following SDML tags: 

<INCLUDE>(CL0SE_GR0UP.SDML) 

<INCLUDE>(0PEN_GR0UP.SDML) 

<INCLUDE>(READ.GROUP.SDML) 

<INCLUDE>(WRITE.GROUP.SDML) 
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<STATEMENT_SECTION> 


Each of the included files contains one statement reference description 
begun with a < STATEMENT > or < FUNCTION > tag. For these files to process 
correctly, they must be preceded with the < STATEMENT-SECTION > tag that 
enables the <statement> and <function> tag. These files can have the 
necessary tags processed before them by specifying the /INCLUDE qualifier 
on the command line to include a startup definition file. This startup file 
might include the following tags: 

<STATEMENT_SECTION>(Group Statements\GS) 

<SET_TEMPLATE_STATEMENT>(STATEMENT\DOUBLERUNNINGHEADS) 

If this startup file were named GS_STATEMENT_STARTUP.SDML, it could 
be included using the DOCUMENT /INCLUDE qualifier as in the following 
example: 

$ DOCUMENT mystatements SOFT.REF LN03 /INCLUDE=GS_STATEMENT_STARTUP.SDML 

When each individual file in MYSTATEMENTS.SDML is processed, the 
correct sequence of tags is read in to begin the statement section. 

You can process multiple files together by using the < INCLUDE > tag to 
include them into a single master file (such as MYSTATEMENTS.SDML), or 
you can include them into a book build profile. 

Use the <ELEMENT> tags to include multiple files into a profile. For example, 
the book build profile file GS_STATEPRO.SDML could contain the following 
tags: 

<PR0FILE> 

<ELEMENT>(CLOSE.GROUP.SDML) 

<ELEMENT>(OPEN.GROUP.SDML) 

<ELEMENT>(READ_GROUP.SDML) 

<ELEMENT>(WRITE_GROUP.SDML 

<COMMENT>(**contains <ENDSTATEMENT_SECTION> tag**) 

<ENDPROFILE> 

Note that the profile file should include the <ENDSTATEMENT_SECTlON> tag 
in the appropriate file, so that the template will be terminated and the book 
build will process correctly. 
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14.6 The Tag Reference Template Tags 

This section alphabetically describes the tags available in the Tag template. 

Use these tags to create a tag reference section. In most manuals, a tag 
reference section is an encyclopedic reference section that describes each tag 
the software system offers, along with the tag's format, its arguments, and 
examples of its use. 
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<FORMAT> 


<FORMAT> 

Begins a section that highlights the syntax of a tag, including keywords 
and arguments. 

FORMAT 

<FORMAT> [(alternate-heading)] 

ARGUMENTS 

alternate-heading 

Specifies a heading to override the current default text heading for this use of 
the < FORMAT > tag. The default heading provided by VAX DOCUMENT is 
"Format." See the <set_template-HEADING > tag description for information 
on how to modify the default headings for all <FORMAT> tags. 

related tags 

• <FTAG> 

• <TAG_SECTION> 

restrictions 

None. 

required 

<ENDFORMAT> 

terminator 

DESCRIPTION 

The < FORMAT > tag creates sections of text that describe the format of a 
command, routine, or tag. This tag is a global tag and is not restricted to 
tag sections. However, in the context of the < ROUTINE-SECTION > and 
< TAG-SECTION > tags, the < FORMAT > tag enables certain additional tags 
for specialized format descriptions. These additional tags are not available 
outside of the context of routine or tag sections. 

The global <format> tag enables the <fcmd> , <fparms> , and 
<FPARM> , which label specific portions of a format statement. In a tag 
section, the < FORMAT > tag also enables the <ftag> tag to describe the 
syntax of VAX DOCUMENT tags. 

EXAMPLE 

The following example illustrates a simple format section using the <FTAG> 
tag to describe the format of the < FRUIT-TYPE > tag. 

<F0RMAT> 

<FTAG>(FRUIT_TYPE\fruit-arg) 

<ENDFORMAT> 


This example may produce the following output. 

FORMAT 

<FRUIT_TYPE> (fruit-arg) 
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<FTAG> 

<FTAG> 

Specifies the name of a tag and its arguments within the context of a 
<FORMAT> tag. 

FORMAT 

<FTAG> (tag-name[\ argument-list [\ OPTIONAL]]) 

ARGUMENTS 

tag-name 

Is the name of the tag. This name must be a valid tag name. 

argument-list 

Lists the arguments, if any. If this argument is not specified, it indicates that 
the tag has no arguments. 

When you specify arguments, you can use the <ARG_SEP> tag to denote the 
argument separator character, the backslash (\). 

OPTIONAL 

Indicates that all arguments are optional. When this keyword is specified, 
the argument-list argument is placed in square brackets to indicate that those 
arguments are optional. 

related tags 

• <FORMAT> 

• <ARG_SEP> 

restrictions 

Valid only within the context of a <FORMAT> tag section in the Tag 
Template. 

required 

terminator 

None. 

DESCRIPTION 

The <FTAG> tag is used to describe the format of a tag and its arguments 
within a format section. This tag uses the <arg_sep> tag to create tag 
separator characters (\) within the argument-list argument. 


The <ARG_SEP> tag has no other function than to output the tag separator 
character (the backslash) within a Tag template format section. 


14-183 






SOFTWARE Doctype Tag Reference 

<FTAG> 


EXAMPLES The following example shows how you can use the <FTAG> tag to show the 

syntax of a tag that has no argument list. 

^ <format> 

<ftag>(OVERVIEW) 

<endformat> 

This example may produce the following output. 


FORMAT <OVERVlEW> 


The following example illustrates how to specify the format of a tag that has 
a single optional argument by using the OPTIONAL keyword. 


<format> 

<ftag>(DESCRIPTION\heading-text\OPTIONAL) 

<endformat> 


This example may produce the following output. 


FORMAT <DESCR1PTI0N> [(heading-text)] 

The following example illustrates how to specify a tag that has one required 
and two optional arguments. Note how the <arg_sep> tag is used to 
separate the arguments. 

2 <format> 

<ftag>(ROUTINE\name[<arg_sep>info-l[<arg_sep>info23]) 

<endformat> 

This example may produce the following output. 


FORMAT <ROUTIIVIE> (name]\ info-1[\ info2]]) 


The following example shows a tag format in which all of the tag's arguments 
are optional and positional. 

<format> 

<ftag>(ROUTINE_SECTION\[running-title]<line> 

[<arg_sep>prefix]<line> 

[<arg_sep>NEWPAGE]\0PTI0NAL) 

<endformat> 

This example may produce the following output. 


FORMAT <ROUTIIME_SECTION> [([running-title] 

[\ prefix] 
[\NEWPAGE]}] 
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<RELATED 

_ITEM> 

Provides a text description of a set of tags or the use of a set of tags that 
may be related to the tag being described. 

FORMAT 

<RELATED_ITEM> 

ARGUMENTS 

None. 

related tags 

• <RELATED_TAGS> 

• <RELATED_TAG> 

restrictions 

Valid only within the context of a <RELATED_TAGS> tag section. 

required 

terminator 

None. 

DESCRIPTION 

The < RELATED-ITEM > tag lets you introduce text into a <related_tags> 
tag section' This text begins right after the <RELATED_ITEM> tag and is 
terminated by the next related tag section tag. 


EXAMPLE The following example shows how to enter text describing information related 

to the use of a tag. 


<RELATED_TAGS> 

<RELATED_ITEM> The <TAG>(INTRO) and <TAG>(ENDINTRO) tags 
may be used to label the introductory material in your book. 

<ENDRELATED_TAGS> 

This example may produce the following output. 


related tags • The <intro> and <endintro> tags may be used to label the 

introductory material in your book. 
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<RELATED_TAG> 


< RELATED 

_TAG> 

Specifies a single tag that is related to the current tag. 

FORMAT 

<RELATED_TAG> (tag-name) 

ARGUMENTS 

tag-name 

Specifies the name of a VAX DOCUMENT tag. Do not place angle brackets 
around the tag name, these are supplied by the <RELATED_TAG> tag upon 
output. 

related tags 

• <RELATED_TAGS> 

• < RELATED-ITEM > 

restrictions 

Valid only within the context of the <RELATED_TAGS> tag. 

required 

terminator 

None. 

DESCRIPTION 

Use the <related_tag> tag to list a single related tag in the context of the 
<RELATED-TAGS > tag. This tag automatically places angle brackets around 
the tag-name argument, so angle brackets should not be specified. 

Use the < RELATED-ITEM > tag to list related tag information in another 
format. 


EXAMPLE The following example specifies the names of two related tags in the context 

of the <RELATED_TAGS> tag. Note how the names of the related tags are 
specified without the angle brackets. 


<RELATED_TAGS> 

<RELATED_TAG>(TAG.SECTION) 

<RELATED_TAG>(SET_TEMPLATE_TAG) 

<ENDRELATED_TAGS> 

This example may produce the following output. 


related tags • <tag_section> 

• <SET_TEMPLATE_TAG> 
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<RELATED_TAGS> 


<RELATED 

_TAGS> 

Provides a summary of tags whose use is related to the tag being 
described. 

FORMAT 

<RELATED-TAGS> [(NONE)] 

ARGUMENTS 

NONE 

Indicates that there are no tags whose use is related to the tag being 
described. If the NONE keyword argument is used, do not specify the 
<ENDRELATED-TAGS> tag. 

related tags 

• < RELATED-TAG > 

• <RELATED-ITEM> 

restrictions 

If NONE is specified, you must not specify <ENDRELATED-TAGS> . 

required 

terminator 

<ENDRELATED-TAGS> 


EXAMPLES The following example shows how to specify two related tags in a < RELATED- 

TAGS > tag section. 


<RELATED_TAGS> 

<RELATED_TAG>(TAG_SECTION) 
<RELATED_TAG>(SET_TEMPLATE_TAG) 
<ENDRELATED_TAGS> 


This example may produce the following output. 


related tags • <tag_section> 

• < SET-TEMPLATE-TAG > 

The following example shows how to use the NONE keyword to show that 
there are no related tags. Note that, in this case, the <ENDRELATED-TAGS> 
tag is omitted. 
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<RELATED_TAGS> 


2 <RELATED_TAGS>(NONE) 

This example may produce the following output. 


related tags None. 

The following example shows how text describing information related to the 
use of the tag can be entered into the <RELATED_TAGS> tag section using the 
< RELATED-ITEM > tag. 

S <RELATED_TAGS> 

<RELATED_ITEM>The <tag>(SIDE_EFFECTS) and <tag>(ENDSIDE_EFFECTS) tags 
accept the same arguments as the <tag>(45RPM) tag. 

<ENDRELATED_TAGS> 

This example may produce the following output. 


related tags • The <side_effects> and <endside_effects> tags accept the same 

arguments as the <45RPM> tag. 
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<RESTRICTIONS> 


<RESTRICTIONS> 


Provides a summary of restrictions on the use of a tag. 


FORMAT 


<RESTRICTIONS> 



alternate-heading 

NONE 

LIST 



t alternate-heading \ LIST J 


ARGUMENTS 


related tags 


alternate-heading 

Specifies a heading to override the current default text heading for this 
use of the < RESTRICTIONS > tag. The default heading provided by 
VAX DOCUMENT is "Restrictions." See the reference description of the 
<SET_TEMPLATE_HEADING> tag for information on how to modify the default 
headings for all < RESTRICTIONS > tags. 

NONE 

Indicates that there are no restrictions on the use of the tag. If the NONE 
keyword is used, do not use the <ENDRESTRlCTlONS> tag to end the 
<RESTRICTIONS > tag section. 

LIST 

Indicates that a number of restrictions are to be listed. To list the restrictions, 
use the <RITEM> for each of the individual restriction items in the list. 


• < TAG-SECTION > 

• <RITEM> 


restrictions 


If NONE is specified, you must not specify the <ENDRESTRlCTlONS> tag. 


required 

terminator 


< ENDRESTRICTIONS > 


EXAMPLES The following example shows how to set a simple paragraph of text for the 

restrictions section using the <RESTRlCTlONS> tag. 

Q <RESTRICTIONS> 

Valid only in the context of the 
<tag>(COMMAND_SECTION) tag. 

<ENDRESTRICTIONS> 


This example may produce the following output. 


restrictions 


Valid only in the context of the < COMMAND-SECTION > tag. 
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<RESTRICTIONS> 


The following example shows how to use the NONE keyword to indicate that 
there are no restrictions on the use of a tag. 

g <RESTRICTIONS>(NONE) 

This example may produce the following output. 

restrictions None. 

The following example shows how to create a set of restrictions in a list. 

B <RESTRICTIONS>(LIST) 

<RITEM>If you specify NONE, you must not specify <tag>(ENDPARAMDEFLIST). 

<RITEM>Use of a default heading is restricted to the reference templates. 

<ENDRESTRICTIONS> 

This example may produce the following output. 


restrictions • if you specify none, you must not specify <ENDPARAMDEFLIST> . 

• Use of a default heading is restricted to the reference templates. 
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<RITEM> 


<RITEM> 

Labels an item in a list of restrictions. 

FORMAT 

<RITEM> 

related tags 

• <RESTRICTIONS> 

restrictions 

Can only be used in the context of the < RESTRICTIONS > tag. 

required 

terminator 

None. 

EXAMPLE The following example shows how to create a list of restrictions. Note how 

the <RESTRlCTiONS> tag is specified with the LIST keyword argument. Note 
how this enables the <RITEM> tag. 

<RESTRICTIONS>(LIST) 

<RITEM>You must not unplug this appliance while it is operating. 

<RITEM>This appliance should not be immersed in water. 

<ENDRESTRICTIONS> 

This example may produce the following output. 

restrictions 

• You must not unplug this appliance while it is operating. 

• This appliance should not be immersed in water. 
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<SDML_TAG> 


<SDML_TAG> 

Begins a new tag description. 

FORMAT 

<SDMI_TAG> (tag-name) 

ARGUMENTS 

tag-name 

Specifies the name of the tag to be described. 

related tags 

• < SET-TEMPLATE-TAG > 

• < TAG-SECTION > 

required 

terminator 

None. 

DESCRIPTION 

Use the <SDML-TAG> tag to begin a description section for a single SDML 
tag. The <sdmL-TAG> tag has the following default format: 

• Each <SDML-TAG> tag begins a new page of output. 

• Each output page carries a single running title, which is the current SDML 
tag name. 

Use the <set-TEMPLATE-Tag> tag to replace the <sdml-TAG> tag with a 
tag whose name is more meaningful to you (for example, < local-TAG > ), 
or if you wish to change the default attributes of the <sdmL-TAG> tag. See 
the description of the < SET-TEMPLATE-TAG > tag in this chapter for more 
information. 

EXAMPLE 

The following example shows the Tag template begun using the <taG- 
SECTlON> tag. Within this tag section the < SDML-TAG > tag is used to begin 
the tag description for the local <leveli> tag. 


<TAG_SECTION>(Local Tags) 
<SDML_TAG>(LEVEL1) 

<0VERVIEW> 

Labels the first level of a diagram. 
<ENDOVERVIEW> 


14-192 






SOFTWARE Doctype Tag Reference 

<SET_TEMPLATE_TAG> 


< SET_TEM PLATE ^TAG > 


Defines a new reference element tag name to use in the tag template, and 
specifies formatting attributes for the newly-defined tag. 


FORMAT <SET_TEMPLATE_TAG> (tag-name 

[ \ attribute] 
[ \ attribute] 
[\ attribute]) 


ARGUMENTS tag-name 

Specifies the name of the template tag being defined. This tag name must 
be a valid tag name less than 31 characters; it must not be the same as an 
existing SDML tag name other than "SDML_TAG" (which is the default tag 
name). 

attribute 

Specifies one of three keywords that allow the user to override the default 
attributes for the <SDML_tag> tag. Specify each attribute as a separate 
argument. 

• NONEWPAGE 

Specifies that tag descriptions are not to start on new pages. By default, 
each tag-name template tag begins a tag description on a new page. 

• DOUBLERUNNINGHEADS 

Specifies that the tag descriptions for the tag-name tag will have two 
running titles at the top of every page. The top running title is set by the 
<TAG_SECTlON> tag or by the heading of the most recent <CHAPTER> 
or <APPENDIX> tag. By default, if a doctype does not call for running 
top titles, only the current tag name is placed at the top of each page. 

• STACK 

Specifies that when multiple arguments are specified for the tag-name tag, 
the arguments should be stacked at the beginning of the page. 

By default, when multiple arguments are specified, the second and third 
arguments are assumed to be optional descriptive information, and are 
output on the same line as the tag name. 


related tags • <sdml_tag> 

• <TAG_SECTION> 


restrictions Valid only within the context of the <TAG_SECTlON> tag. 
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<SET_TEMPLATE_TAG> 


required None. 

terminator 


DESCRIPTION The <SET_TEMPLATE_TAG> tag allows you to specify the name by which you 

want to refer to tags that you are describing in the context of a template. 

This tag also allows you to alter the default attributes associated with the 
<SDML_TAG> tag (or the tag you replaced with the <SDML_TAG> tag using 
the <SET_TEMPLATE_TAG> tag). 


EXAMPLE The following example shows how to use the <SET_template_tag> tag to 

alter the default format of the Tag template. 

<TAG_SECTION>(Tag Template Tags) 

<SET_TEMPLATE_TAG>(LOCAL_TAG\DOUBLERUNNINGHEADS) 

<L0CAL_TAG>(LEVELl) 


This tag sequence begins a tag section and defines the tag < LOCAL _TAG> for 
introducing new tag descriptions. These attributes are as follows: 

• Each tag description begins on a new page. 

• Each page carries a two-line running title. The top line is "Tag Template 
Tags" and the second line is the name of the tag description that is current 
at the top of the page. 
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<TAG_SECTION> 


<TAG_SECTION> 


Begins a tag reference section, enables tags reserved for use in tag 
sections, and sets paging attributes. 


FORMAT 


<TAG_SECTION> [([running-title] 

[ \ number-prefix] 
[\NEWPAGE])] 


ARGUMENTS running-title 

Specifies a top-level running heading to be used throughout the tag section. 
If this argument is not specified, the running headings are determined as 
described in Section 8.4.2. 

number-prefix 

Specifies a character-string prefix to be used to construct page numbers 
(folios) and formal figure, table, and example numbers. If this argument is 
not specified, the page and formal element numbering are determined as 
described in Section 8.4.2. 

NEWPAGE 

Indicates that the tag section should begin on a new page. This argument is 
only meaningful in two cases: 

• When you have previously entered the <SET_TEMPLATE_TAG> tag with 
the NONEWPAGE keyword to specify that each new tag in this tag 
section should not begin on a new page. 

• When you want to place one or more pages of text between the end of a 
part page and the beginning of a tag section. 


related tags • <set_template_tag> 

• <SET_TEMPLATE_PARA> 

• <SET_TEMPLATE_LIST> 

• < SET-TEMPLATE-TABLE > 

• <SET-TEMPLATE-HEADING> 

• <SDML-TAG> 

• <OVERVIEW> 

• < FORMAT > 

• <FTAG> 

• <PARAMDEFLIST> 

• < RELATED-TAGS > 

• < RELATED-TAG > 
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<TAG_SECTION> 


restrictions 

required 

terminator 

DESCRIPTION 


• <RELATED_ITEM> 

• < RESTRICTIONS > 

• <RITEM> 

• < TERMINATING-TAG > 

• < DESCRIPTION > 

• <EXAMPLE_SEQUENCE> 


None. 


<ENDTAG_SECTION> 


The <TAG_SECTI0N> tag begins the tag reference template. You can locate 
a tag section within a chapter or an appendix, or following a part page (that 
is, within a document section begun with the <PART_PAGE> tag). You code 
a tag section in a chapter or an appendix in the same manner; tag sections in 
parts are handled differently. 

If your tag section follows a part page, and you include text between the 
part page and the tag section, specify the NEWPAGE keyword as the third 
argument to the <TAG_SECTiON> tag. This causes the tag section to begin 
on a new page. The following code fragment shows a tag section that begins 
on a new page: 

<TAG_SECTION>(\TD\NEWPAGE) 

<HEADl>(Tag Dictionary) 

When you use the < tag-SECTION > tag within a chapter or an appendix, and 
want to place text after the tag section in that chapter or appendix, you must 
end the tag section with the <endtaG-SECTION> tag and place the text after 
that tag. By default, this text begins on a new page of output. 

Specify the NONEWPAGE argument to the <ENDTAG-SECTION > tag if you 
do not want the text to begin on a new page of output. The following code 
fragment shows the end of a tag section that specifies that the subsequent text 
not be placed on a new page: 

<ENDTAG_SECTION>(NONEWPAGE) 

When the <endtag_SECTION> tag is specified within the context of a 
chapter or appendix, it resets the default running titles to those in effect for 
the chapter or appendix, so the last page of the last tag description in the tag 
section may not carry the last tag's name as the running heading. Instead it 
may carry the running title used by the chapter or appendix. 
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<TAG_SECTION> 


EXAMPLES The following example shows how to begin a tag section within a document 

part. 

n <PART> 

<PART_PAGE> 

<TITLE>(Part III\Tag Dictionary) 

<ENDPART_PAGE>(RENUMBER) 

<TAG_SECTION>(Tag Dictionary\TD) 

<SET_TEMPLATE_TAG>(LOCAL.TAG) 

<L0CAL_TAG>(SITETAG) 

<0VERVIEW> 

This is a site-specific tag. 

<ENDOVERVIEW 


<ENDTAG_SECTION> 

The tags in the previous example perform the following functions: 

• The global <PART> tag begins the part. 

• The global <part_page> tag creates a part page. 

• The global <title> tag is used in the context of the <part_page> tag 
to create a title on the part page. 

• The RENUMBER argument to the global <endpart_page> tag specifies 
that the pages should be renumbered beginning with the part page. This 
causes the first page of text following the part page to be numbered page 
3 (Page 1 is the unnumbered page the part page title is placed on, page 2 
is the back of page 1, and page 3 is the first numbered page after the part 
page).. 

• The <TAG_SECTiON> tag begins the tag Section and specifies the running 
title "Tag Dictionary" as the running title for the tag section. If the <SET_ 
TEMPLATE_TAG> tag were used with the DOUBLERUNNINGHEADS 
argument, the title "Tag Dictionary" would be used as the top running 
title. 

The <TAG_SECTiON> tag also specifies that the prefix "TD" should be 
used to construct numbers for pages and for formal figures, tables, and 
examples within the tag section (for example, TD-11, TD-32, Table TD-1, 
Example TD-2, and so on). 

• The <SET_TEMPLATE_TAG> tag Specifies that all tag descriptions in this 
tag section will be identified using the tag < LOCAL _TAG> rather than 
the default tag <tag> . The < local _tag> tag will have the default 
attributes of the <TAG> tag. 

The following example shows how you can create a tag section in which each 

tag description (begun with a <SDML_TAG> tag) is in a separate SOME file, 

and all these descriptions are included into a primary routine description file. 

For example, the file MYTAGS.SDML contains the following SDML tags: 

<INCLUDE>(CLOSE_FILE.SDML) 

<INCLUDE>(OPEN_FILE.SDML) 

<INCLUDE>(READ.FILE.SDML) 

<INCLUDE>(WRITE_FILE.SDML) 
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<TAG_SECTION> 


Each of the included files contains one tag reference description begun with a 
<SDML_TAG> tag. For these files to process correctly, they must be preceded 
with the <TAG_SECTiON> tag that enables the <SDML_tag> tag. These 
files can have the necessary tags processed before them by specifying the 
/INCLUDE qualifier on the command line to include a startup definition file. 
This startup file might include the following tags. 

2 <TAG_SECTION>(File Handling Tags\TAGS) 

<SET_TEMPLATE_TAG>(SDML_TAG\DOUBLERUNNINGHEADS) 

If this startup file were named FILE—TAG—STARTUP.SDML, it could be 
included using the DOCUMENT /INCLUDE qualifier as in the following 
example: 

$ DOCUMENT mytags SOFT.REF LN03 /INCLUDE=FILE_TAG_STARTUP.SDML 

When each individual file in MYTAGS.SDML is processed, the correct 
sequence of tags will be read in to begin the tag section. 

You can process multiple files together by using the < INCLUDE > tag to 
include them into a single master file (such as MYTAGS.SDML), or you can 
include them into a book build profile. 

You use the <element> tags to include multiple files into a profile. For 
example, the book build profile file TAGPRO.SDML could contain the 
following tags: 

<PR0FILE> 

<ELEMENT>(CLOSE.FILE.SDML) 

<ELEMENT>(OPEN.FILE.SDML) 

<ELEMENT>(READ.FILE.SDML) 

<ELEMENT>(WRITE_FILE.SDML) <C0MMENT>(contains <ENDTAG_SECTION> tag) 
<ENDPROFILE> 

Note that the profile file should include the <ENDTAG_SECTlON> tag in the 
appropriate file, so that the template will be terminated and the book build 
will process correctly. 
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DESCRIPTION The < TERMINATING-TAG > tag specifies the tag required to terminate the 

tag that is being described. You can provide additional information about 
the terminating tag by specifying this text as the second argument to the 
< TERMINATING-TAG > tag. 

Use the NONE keyword argument to explicitly specify that no terminating 
tag is needed. This keyword places the text "None." beneath the heading 
output by this tag. 
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<TERMINATING_TAG> 


EXAMPLES The following example shows a terminating tag specified with both the 

tag-name argument and also the additional-text argument. 

Q <TERMINATING_TAG>(ENDRECORDLIST\<p>This tag should be omitted if the 
NONE keyword is used with the <TAG>(RECORDLIST) tag.) 

This example may produce the following output. 


required <endrecordlist> 

terminator This tag should be omitted if the NONE keyword is used with the 

<RECORDLIST> tag. 

The following example shows the <TERMINATING_TAG> tag used with the 
NONE keyword. 

g <TERMINATING_TAG>(NONE) 

This example may produce the following output. 


required None. 

terminator 
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Reference • 14-5 
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Reference • 14-126 
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<coLUMN> tag (cont'd.) 
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Reference* 14-27 
Extracts 
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Reference * 14-14 
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tags* 11-1 to 11-11 
templates * 5-5 
MIL-STD-490A documents 
See MILSPEC doctype 
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<MSGS> tag 

Reference • 14-51 to 14-52 
<MSG> tag 

Reference • 14-49 to 14-50 

<MSG_TEXT> tag 

Reference • 14-53 



Notes 

back notes 

See <BACK_NOTES> tag 
reference notes 

See <REF_NOTES> tag 
source notes 

See <SOURCE_NOTE> tag 



< OUTLINE > tag *7-2 
Reference • 13-16 to 13-17 
OVERHEADS doctype* 6-3 to 6-5 
sample output file • 6-5 
sample SDML file • 6-5 
tags *12-1 to 12-16 
Overhead slide 

See OVERHEADS doctype 
<ovERviEw> tag 
Reference • 14-84 



<PARAMDEFLIST> tag 

Reference • 14-55 to 14-57 

<PARAMDEF> tag 

Reference • 14-54 

<PARAMITEM> tag 

Reference* 14-58 to 14-59 
<pRoiviPTS> tag 

Reference *14-112 
<PR0MPT> tag 

Reference* 14-110 to 14-111 



<QPAIR> tag 

Reference * 14-60 

<QUALDEFLIST> tag 

Reference* 14-67 to 14-69 

<QUALDEF> tag 

Reference * 14-66 

<QUALITEIVI> tag 

Reference * 14-70 to 14-71 

<QUAL_LIST> tag 

Reference * 14-61 to 14-63 

<QUAL_LIST_DEFAULT_HEADS> tag 

Reference * 14-64 

<QUAL_LIST_HEADS> tag 

Reference * 14-65 
<QUOTATION> tag *2-1 
Reference * 9-20 



Reference template 

See SOFTWARE doctype 
<REF_NOTEs> tag *2-2, 2-7 
Reference * 9-23 
<REF_NOTE> tag *2-2, 2-7 
Reference * 9-21 to 9-22 

<RELATED_ITEM> tag 

Reference* 14-185 

<RELATED-TAGS> tag 

Reference * 14-187 to 14-188 

< RELATED-TAG > tag 

Reference *14-186 
REPORT doctype *7-1 to 7-^3 

improving format of REPORT.TWOCOL 
See Two-column doctype 
sample output file * 7-3 
sample SDML file * 7-2 to 7-3 
tags *13-1 to 13-25 

<RESTRicTioNs> tag 

in Command template * 14-113 to 14-114 
in Tag template * 14-189 to 14-190 

<RETTEXT> tag 

Reference* 14-137 

<RETURNS> tag 

Reference * 14-138 to 14-139 

<RETURN-VALUE> tag 

Reference *14-115 
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<RiTEM> tag 

in Command template* 14-116 
in Tag template* 14-191 

< ROUTINE > tag 

Reference * 14-140 to 14-141 
Routine template 

See SOFTWARE doctype 

< ROUTINE-SECTION > tag 

Reference * 14-142 to 14-145 

<RSDEFLisT> tag 

Reference * 14-146 to 14-147 

<RsiTEM> tag 

Reference* 14-148 
Running headings 
at bottom of page 

See <RUNNING_FEET> tag 

at top of page 

See < RUNNING-TITLE > tag 

<RUNNING-FEET> tag 

in ARTICLE doctype * 2-2, 2-5 
Reference * 9-24 
in OVERHEADS doctype *6-4 
Reference * 12-6 to 12-7 
in REPORT doctype *7-2 
Reference* 13-18 
in SOFTWARE doctype 
Reference* 14-72 

< RUNNING-TITLE > tag 

in ARTICLE doctype *2-2, 2-5 
Reference *9-25 to 9-26 
in OVERHEADS doctype *6-4 
Reference * 12-8 to 12-9 
in REPORT doctype * 7-2 

Reference * 13-19 to 13-20 
in SOFTWARE doctype 

Reference* 14-73 to 14-74 


s 


<SALUTATioN> tag * 3-2 
Reference* 10-22 

<SDML-TAG> tag 

Reference* 14-192 
<SECTioN> tag *7-2 

Reference* 13-21 to 13-22 

<SET-APPENDIX-NUMBER> tag * 5-1 

Reference * 11 -2 to 11-3 

< SET-TEMPLATE-COMMAND > tag 

Reference * 14-117 to 14-118 


<SET-TEMPLATE-HEADING> tag 

Reference* 14-85 to 14-86 

<SET_TEMPLATE_LIST> tag 

Reference* 14-87 to 14-88 
<set-Template-para> tag 
Reference * 14-89 to 14-90 

<SET-TEMPLATE-ROUTINE> tag 

Reference * 14-149 to 14-151 

<SET-TEMPLATE-STATEMENT> tag 

Reference * 14-169 to 14-170 

<SET_TEMPLATE-SUBCOMMAND> tag 

Reference * 14-119 to 14-120 

<SET-TEMPLATE-TABLE> tag 

Reference * 14-91 to 14-94 

<SET-TEMPLATE-TAG> tag 

Reference * 14-193 to 14-194 
<SH0W-LEVELS> tag * 7-2 

Reference * 13-23 to 13-24 

<siGNATUREs> tag 

in REPORT doctype *7-1 
Reference * 13-25 
in SOFTWARE doctype 
Reference* 14-75 

<SIGNATURE_LINE> tag * 5-1 

Reference * 11 -4 to 11-5 

<SIGNATURE-LIST> tag *5-1 

Reference * 11 -6 to 11-7 
Slides 

See OVERHEADS doctype 
<SLiDE> tag *6-4 

Reference * 12-10 to 12-11 
SOFTWARE doctype *8-1 to 8-57 
arguments, parameters and qualifiers* 

8-14 to 8-17 

code fragments * 8-8 to 8-10 

interactive or code examples * 8-18 to 8-19 

messages 

See software messages *8-10 
reference templates * 8-19 to 8-57 
Command template *8-35 to 8-42 
sample output file * 8-39 to 8-42 
sample SDML file * 8-37 to 8-38 
Routine template * 8-42 to 8-48 
sample output file * 8-44 to 8-48 
sample SDML file*8-43 to 8-44 
Statement template * 8-48 to 8-53 
sample output file * 8-50 to 8-53 
sample SDML file * 8-49 
Tag template * 8-53 to 8-57 

sample output file*8-55 to 8-57 
sample SDML file * 8-54 


Index-5 


Index 


SOFTWARE doctype (cont'd.) 

software messages • 8-10 to 8-13 
tags • 14-1 to 14-200 

in all of doctype* 14-1 to 14-79 
in all templates* 14-80 to 14-94 
in Command template * 14-94 to 14-125 
in Routine template * 14-125 to 14-151 
in Statement template* 14-151 to 14-181 
in Tag template * 14-181 to 14-200 
terminal keys and keypads *8-2 to 8-8 
Software messages 

See SOFTWARE doctype 
Software specifications 
See MILSPEC doctype 
See SOFTWARE doctype 
<souRCE_NOTE> tag *2-2, 2-4 
Reference * 9-27 
Specifications 
for military 

See MILSPEC doctype 
for software 

See SOFTWARE doctype 
<sPEciFiCATioN_iNFO> tag * 5-1 
Reference * 11 -8 to 11-9 
<SPEC_TITLE> tag *5-1 
Reference* 11-10 

<STATEIVIENT> tag 

Reference* 14-171 
Statement template 

See SOFTWARE doctype 

<STATEMENT_FORMAT> tag 

Reference* 14-172 to 14-173 

<STATEMENT_L1NE> tag 

Reference* 14-174 to 14-176 

<STATEMENT_SECTION> tag 

Reference * 14-177 to 14-181 
<suBCOMMAND> tag 

Reference * 14-121 to 14-122 

<SUBCOMMAND_SECTION> tag 

Reference *14-123 

<SUBCOMMAND_SECTION_HEAD> tag 

Reference * 14-124 to 14-125 
<suBJECT> tag *3-2 
Reference * 10-23 
<suBTiTLE> tag *6-4 

in ARTICLE doctype • 2-2, 2-3 
Reference * 9-28 
in MILSPEC doctype *5-1 
Reference* 11-11 
in OVERHEADS doctype 
Reference* 12-12 


<SYNTAX> tag 

Reference * 14-76 to 14-77 

<SYNTAX_DEFAULT_HEAD> tag 

Reference * 14-78 to 14-80 


T 


Tag template 

See SOFTWARE doctype 

<TAG_sECTioN> tag 

Reference * 14-195 to 14-198 
Technical manual 

for military specifications 
See MILSPEC doctype 
for software 

See SOFTWARE doctype 
general purpose 

See MANUAL doctype 
Technical report 

See REPORT doctype 
Templates 

See MILSPEC doctype 
See SOFTWARE doctype 

<TERMINATING_TAG> tag 

Reference * 14-199 to 14-200 
<TEXT_sizE> tag *6-4 
Reference* 12-13 to 12-14 
<TiTLE> tag *6-4 

in ARTICLE doctype *2-2, 2-3 
Reference * 9-29 
in OVERHEADS doctype 
Reference *12-15 
<TiTLE_SECTioN> tag • 2-2 

Reference * 9-30 
<T0Pic> tag *6-4 
Reference *12-16 
<T0_ADDRESS> tag * 3-2 
Reference* 10-24 
Transparency 

See OVERHEADS doctype 
Two-column doctype 

improving the format of *2-8 


V 


<viTA> tag *2-2, 2-3 
Reference * 9-31 to 9-32 
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Note: This form is for document comments only. DIGITAL will use comments 
submitted on this form at the company's discretion. If you require a written 
reply and are eligible to receive one under Software Performance Report (SPR) 
service, submit your comments on an SPR form. 


Did you find this manual understandable, usable, and well organized? Please make suggestions for 
improvement. 


Did you find errors in this manual? If so, specify the error and the page number. 


Please indicate the type of user/reader that you most nearly represent: 

□ Assembly language programmer 

□ Higher-level language programmer 

□ Occasional programmer (experienced) 

□ User with little programming experience 

□ Student programmer 
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